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Introducing the BREW OEM 


API Reference for MSMTM 
Platform 


This document provides manufacturers with information about the Binary Runtime 
Environment for Wireless"M (BREW"M) OEM functions. With these functions, OEM devices 
become BREW-enabled. 


In this reference 


This remainder of the this reference manual contains the following sections: 


BREW API Interfaces Describes the BREW interfaces and functions that are used by the 
OEM APIs. 
Data Types Describes the data structures that are used by the OEM APIs. 


Functions and Data types Provides an alphabetic listing of all functions and data types 


discussed in this reference. 


Each function is listed with the following Information: 


Description: 
Prototype: 


Parameters: 


Return Values: 


Comments: 


Side Effects: 


See Also: 


An explanation of the function's use. 
A sample of the structure of a call. 
The items to be input and the items returning. 


The items returning from the function call, including types, messages, values, 
structures, and descriptions. 


Any special considerations and extra information to assist in understanding the 
function's use, limitations, and boundaries. 


Any behavior that the function exhibits that may not be normally considered when 
using a function call. This heading only appears when there is a side effect. 


Cross-references to any related function or data structure. 
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BREW SDK"” documentation set 


The BREW documentation set contains the following documents: 


BREW SDK User's Guide Introduces the components of the BREW Software Development Kit 
(BREW SDK7M) and their relationship to one another. The document 
also contains general instructions for developing BREW applications 
and for using the BREW Emulator. 


BREW API Reference Provides information about BREW functions and data structures 
needed to develop applications for BREW-enabled mobile platforms. 

BREW Device Configurator Describes how to use the BREW Device Configurator to create 

Guide effective wireless devices for emulation by the BREW Emulator. 


BREW Resource Editor Guide 'Describes how to use the BREW Resource Editor to create the text 
strings, images, and dialogs for BREW applications. 


BREW MIF Editor Guide Describes how to use the BREW MIF Editor to create and modify 
MIFs—a special type of BREW resource file that contains information 
about the classes and applets supported by particular BREW 
modules. 


BREW SDKTM Utilities Guide Describes how to use the utilities, such as the PureVoice Converter, 
included with the BREW SDK. 


BREW Compressed Image Describes how to use the BREW Compressed Image Authoring Tool 
Authoring Guide to create files for displaying and animating images in your 
applications. 


BREW OEM documentation set 


The BREW OEM documentation set includes the following documents: 


BREW OEM Porting Guide Describes the interfaces required from the OEM that allow the 
BREW AEE to provide various applications services. 


BREWapi OEM API Reference Describes the OEM mobile interface layer (MIL) and chip interface 
layer (ChlL) details. 


BREW OEM Application Test (OAT) Describes which tests to run and how to run them. 
Guide 


BREW Core Application Guide Provides MobileShop/Application Manager application 
requirements and reference UI specs for an OEM that is 
developing a device for a carrier. 


BREWsStone"M User's Guide Describes the Brewstone benchmarking tool designed to test the 
efficiency of BREW devices against the base device QCP3035. 
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BREW OEM acronyms 


ADS 
AEE 
APCS 
API 
ARM 
ASIC 
BREW 
ChiL 
ClassID 


DC 
DMSS 


Interface 


ISOD 
MIDI 
MIF 


MIL 
MIME 
NVRAM 
OAT 
OEM 


PNG 
RAM 
SDK 
sDT 
SMS 


Application Download Server 

Application Execution Environment 

ARM Procedure Call Standard 
Application Programming Interface 
Asynchronous Response Mode 
Application-specific integrated circuit 
Binary Runtime Environment for Wireless. 
Chip Interface Layer 


32-bit IDs for identifying BREW classes and applets. These IDs are assigned at the 
site www.qualcomm.com/brew/sdk/classid. BREW ClasslDs are available to 
authenticated developers only. 


Display Context 
Dual Mode Subscriber Software 


An abstract class providing a set of methods for a specific service. For example, 
the IDisplay interface provides a set of methods for basic display services. Each 
interface has a unique class identifier (AEECLSID), and the name of each interface 
begins with the letter “|.” In BREW, all the interfaces are derived from a base level 
class interface called IBase. IBase consists of two standard methods for 
incrementing and decrementing the reference count of an object. This reference 
count mechanism allows an object to be shared by multiple users. 


Internet Protocol 
Interface Specification and Operational Description 
Musical Instrument Digital Interface 


Module Information File. The MIF Editor generates this binary file, which contains 
information regarding the list of classes and applets supported by the modules. 


Mobile Interface Layer 

Multipurpose Internet Mail Extensions 
Non-volatile random access memory 
BREW OEM Acceptance Test 


Original equipment manufacturer 
The phrase 'called by the OEM” means the function is called from the device code. 


Portable Network Graphics 
Random access memory 
Software development kit 
Software development toolkit 


Short message service 
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brew. 
TCP Transmission Control Protocol 
UI OEM device user interface (non-BREW) 
UTF8 Unicode Transformation format 8 bit encoding form. UTF8 serializes a Unicode 
scalar value (code point) as a sequence of one to four bytes. 
Wide string A character string composed of 16-bit characters. Wide strings are used for 


character encoding, such as Unicode that require more than 8 bits per character. 


BREW architecture 


The following figure illustrates BREW architecture and its interaction with other software 
components of the device. 


BREW architecture and interactions 


Chip Specific 
Software 
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For more information 


Online information and support is available for BREW application developers. Please visit the 
BREW web site for details: www.qualcomm.com/brew. 
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AEEBitFont Interface 


The Interface provides a way to create an IFont interface from a Brew Bit Font (BBF). 
List of Header files to be included 
The following header file is required: 
AEEBitFont.h 
List of functions 
Functions in this interface include: 
AEEBitFont NewFromBBF() 


The remainder of this section provides details for each function. 
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AEEBitFont NewFromBBF() 


Description: 


This function may be called by the OEM layer to create an IFont interface from a Brew 
Bit Font (BBF). A BBF is created using the BBFGEN.EXE tool. 


Prototype: 





int AEEBitFont, NewFromBBF 











( 
cons 
int 
void 
PFNR 
IFon 
) 


Parameters: 
pbyMem 
cbMem 


pvStorage 


pfnRealloc 


ppIFont 


Return Value: 


cbMem, 





t **ppIFont 


[in] 
[in] 
[in] 


[in] 


[out] 


SUCCESS if successful. 
EBADPARM if a parameter is invalid. 
EINVALIDFORMAT if pbyMem is not in BBF format. 
ENOMEMORY if not enough memory. 


Comments: 
None. 


*pvStorage, 
EALLOC pfnRealloc, 


t byte *pbyMem, 


Source data in BBF format. 
Size in bytes of the BBF data in pbyMem. 


Controls how the memory in pbyMem![] is treated. It will hold 
one of the following values: 

1. pointer to memory block => the object can retain pointers 
into pbyMem/] instead of copying out the data. If the objects 
successfully created, it will free this pointer using pfnRealloc 
at some point. If creation fails, this pointer will not be freed. 


2. AEEBITFONT COPYDATA => This function must copy 
any data it needs from pbyMem![] before returning. 


3. AEEBITFONT STATICDATA => The IFont will retain 
pointers into pbyMem!/]. It does not need to free anything. 


Pointer to realloc() function to be used for all memory 
allocation and deallocation. This may be NULL, in which case 
the BREW heap will be used for all memory operations. 


New instance of IFont interface created from the BBF. 
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See Also: 


None. 
Return to the List of functions 
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AEE Media Interface 


AEEMedia is the base class of all IMedia-based classes. The Interface provides applications 
the ability to 


* Register the MIME type of the class 

* Make sure a command can be executed in a particular state 

* Manage the IMedia state machine 

* Handle IMedia callbacks and makes callbacks into application 


* Stop IMedia when IMedia is released 


List of Header files to be included 


The following header file is required: 


AEEMedia.h 
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List of functions 


Functions in this interface include: 


AEEMedia AddRef() 
AEEMedia CallbackNotify() 
AEEMedia Delete() 
AEEMedia GetMediaParm() 
AEEMedia GetState() 
AEEMedia GetTotalTime() 
AEEMedia Init() 

AEEMedia New() 
AEEMedia Pause() 
AEEMedia Play() 
AEEMedia Querylnterface() 
AEEMedia Record() 
AEEMedia RegisterNotify() 
AEEMedia Release() 
AEEMedia Resume 
AEEMedia Seek() 
AEEMedia SetMediaParm() 
AEEMedia Stop() 


The remainder of this section provides details for each function. 
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AEEMedia AddRef() 


Description: 
Increments the reference count of IMedia object. 


Prototype: 


uint32 AEEMedia AddRef (IMedia * po); 














Parameters: 
po: Pointer to IMedia 


Return Value: 
Incremented ref count 


Comments: 
None 


See Also: 
AEEMedia Release() 
Return to List of functions 
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AEEMedia CallbackNotify() 


Description: 


This function is registered with CMediaMMLayer for callbacks from the multimedia 
layer. It performs state management and calls the user-registered callback function. 


Prototype: 


void AEEMedia CallbackNotify (AEEMedia * pme, AEEMediaCallback * pmcb); 



































Parameters: 
pme: Pointer to AEEMedia 
pmcb: Pointer to media callback structure 


Return Value: 
None 


Comments: 
This function is called in BREW context. 


See Also: 
AEEMediaCallback 
AEEMedia Play() 
AEEMedia Record() 
AEEMedia Stop() 

Return to List of functions 
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AEEMedia Delete() 


Description: 
This function is the base class destructor. 


Prototype: 


void AEEMedia Delete (IMedia * po); 














Parameters: 
po: Pointer to IMedia 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia GetMediaParm() 


Description: 
This function handles MM PARM MEDIA DATA and MM PARM CLSID. 


Prototype: 


int AEEMedia GetMediaParm 
( 
IMedia * po, 
int nParamID, 
int32 * pP1, 
int32 * pP2 
); 














Parameters: 
po: Pointer to the IMedia Interface object 
nParmlD: MM PARM XXX 
pP1: Depends on parm 
pP2: Depends on parm 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot get parm in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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Era AEE Media Interface 


AEEMedia GetState() 


Description: 


This function returns the current state of IMedia and also indicates the IMedia objectis 
currently in state transition. 


Prototype: 


int AEEMEDIA GetState (IMedia * po, boolean * pbStateChanging); 

















Parameters: 
po: Pointer to the IMedia Interface object 
pbStateChanging: TRUE means IMedia is currently busy transitioning the state. 


Return Value: 
MM STATE XXX 


Comments: 
None 


Side Effects: 


If IMedia is currently is in state transition, then most of IMedia APIs fail and return 
EBADSTATE. 


See Also: 
None 
Return to List of functions 
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AEEMedia GetTotalTime() 


Description: 
This function checks if get total time command is valid in the current IMedia 
state. 


Prototype: 


int AEEMedia GetTotalTime (IMedia * po); 











Parameters: 
po: Pointer to IMedia 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia Init() 


Description: 
This function registers the MIME type in the Shell registry. 


Prototype: 


void AEEMedia Init (IShell * ps, char * szMIME, AEECLSID clsHandler); 





























Parameters: 
ps: Pointer to IShell 
szMIME: MIME string 
clsHandler: Class ID of the IMedia-based class 


Return Value: 
None 


Comments: 
This function is called only once during BREW initialization. 


See Also: 
None 
Return to List of functions 
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AEEMedia New() 


Description: 
This function is the base class constructor. 


Prototype: 


int AEEMedia New (IMedia * po, IShell * ps, AEECLSID cls); 


























Parameters: 
po: Pointer to IMedia 
ps: Pointer to IShell 
cls: Class ID of the IMedia-based class 


Return Value: 
SUCCESS: Successful 


Comments: 
None 


See Also: 
AEEMedia Delete() 
AEEMedia Init() 
Return to List of functions 
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AEEMedia Pause() 


Description: 
This function checks if pause command is valid in the current IMedia 
state. 


Prototype: 


int AEEMedia Pause (IMedia * po); 











Parameters: 
po: Pointer to IMedia 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia Play() 


Description: 
This function checks if playback command is valid in the current IMedia 
state. 


Prototype: 


int AEEMedia Play (IMedia * po); 











Parameters: 
po: Pointer to IMedia 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia Querylnterface() 


Description: 
This function can be used to 
(1) get a pointer to an interface or data based on the input class ID 
(2) query an extended version of the IMedia-derived class 
(3) support version compatibility 























Prototype: 
int AEEMEDIA QueryInterface (IMedia * po, AEECLSID clsReg, void ** ppo); 
Parameters: 
po [in] Pointer to IMedia interface. 
clsReg [in] Aglobally unique id to identify the entity (interface or data) that we 
are trying to query. 
ppo [out] Pointer to the interface or data that we want to retrieve. Ifthe value 
passed back is NULL, the interface or data that we query are not 
available. 


Return Value: 
Return SUCCESS on success, otherwise returns error code. 


Comments: 
If ppo is back a NULL pointer, the interface or data that we query is not 
available. 


Side Effects: 
If an interface is retrieved, then this function incremenits its reference count. 
If a data structure is retrieved, then a pointer to the internal structure is 
given and user should not free it. 


See Also: 
None 
Return to List of functions 
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AEEMedia Record() 














Description: 

This function checks if record command is valid in the current IMedia state. 
Prototype: 

int AEEMedia Record (IMedia * po); 
Parameters: 

po Pointer to AEE Media Interface object. 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 
MM EBADMEDIADATA: Bad media data. Possibly ISource is used for recording. 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia RegisterNotify() 


Description: 
This function registers a callback notification function with IMedia object. 
IMedia reports asynchronous events thorough this callback. 


Prototype: 

int AEEMEDIA RegisterNotify 
( 
IMedia * po, 
PFNMEDIANOTIFY pfnNotify, 
void * pUser 
); 

















Parameters: 
po Pointer to AEE Media Interface object. 
pfnNotify User callback function pointer. 
pUser User data to be used when calling pfnNotify(). 


Return Value: 
SUCCESS: Successful. 
EBADSTATE: Error - IMedia is notin Ready state. 


Comments: 
None 


See Also: 
PFNMEDIANOTIFY 
Return to List of functions 
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AEEMedia Release() 


Description: 
Decrements the reference count of IMedia object. If reference count goes 
down to zero, then it deregisters the user registered callback and 
stops the IMedia playback/recording, if any. 














Prototype: 

uint32 AEEMedia Release (IMedia * po); 
Parameters: 

po Pointer to AEE Media Interface object. 


Return Value: 
Updated reference count. Zero if object is released. 


Comments: 
None 


See Also: 
AEEMedia AddRef() 
Return to List of functions 
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AEEMedia Resume 


Description: 
This function checks if resume command is valid in the current IMedia 
state. 


Prototype: 


int AEEMedia Resume (IMedia * po); 











Parameters: 
po Pointer to AEE Media Interface object. 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia Seek() 


Description: 
This function checks if seek command is valid in the current IMedia state. 


























Prototype: 

int AEEMedia Seek (IMedia * po, AEEMediaSeek eSeek, int32 1lTimeMS); 
Parameters: 

po Pointer to AEE Media Interface object. 

eSeek The seek reference 


ITimeMS The seek time 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 


Comments: 
None 


See Also: 
AEEMediaSeek 
Return to List of functions 
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AEEMedia SetMediaParm() 


Description: 
This function handles MM PARM MEDIA DATA in the Idle state. 


Prototype: 


int AEEMedia SetMediaParm 
( 
IMedia * po, 
int nParamID, 














int32 pl, 
1nt32 p2 
); 
Parameters: 
po Pointer to the AEE Media Interface object 
nParmlD MM PARM XXX 
p1 Depends on parm 
p2 Depends on parm 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot set parm in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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AEEMedia Stop() 


Description: 
This function checks if stop command is valid in the current IMedia 
state. 


Prototype: 


int AEEMedia Stop (IMedia * po); 











Parameters: 
po Pointer to AEE Media Interface object. 


Return Value: 
SUCCESS: Successful 
EBADSTATE: Cannot issue command in the current state 


Comments: 
None 


See Also: 
None 
Return to List of functions 
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OEMMedia DetectType() 


Description: 


Given data in a buffer or the name of an object, this function detects the MIME type of 
the media. This function is typically used to get the handler associated with the data 
type. For example, if the data represents standard MIDI format, then this function 
returns the MIME “audio/mid”. Using the MIME type, you can query Shell registry to 
obtain the handler (Class ID) oftype AEECLSID MEDIA. 


Prototype: 

int OEMMedia DetectType 
( 
const void * cpBuf, 
uint32 * pdwSize, 
const char * cpszName, 
const char ** pcpszMIME 
Di; 








Parameters: 

cpBuf [in] Buffer containing the data whose type needs to be determined 

pdwSize [in/out] On input - Size of data in pBuf, unless pBufis NULL, then ignored 
On output - number of additional data bytes needed to perform 
type detection 

cpszName [in] Name of the object whose type needs to be determined (may be 
null, if unknown). 

pcpszMIME [out] MIME string returned to caller, on return, filled with a pointer to a 


constant string (do not free) 


Return Value: 
SUCCESS: Data type is detected and MIME is returned 
ENOTYPE: There is no type associated with this data 
EBADPARM: Wrong input data (parameter(s)) 


ENEEDMORE: Need more data to perform type detection. *pdwSize contains the 
required number of additional bytes. 


EUNSUPPORTED: Type detection for the specified input is not supported 


Comments: 
pBuf takes precedence over pszName. If both of them are specified, then first pBuf is 
used for type detection followed by pszName. 


If the function returns ENEEDMORE, then *pdwSize is filled with the required 
additional bytes to carry out the operation. Call this function again with (original dwSize 
+ *pdwSize) bytes. 
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To determine the maximum number of bytes required to enable type detection, you can 




















call 
if (ENEEDMORE == ISHELL DetectType (ps, NULL, &dwRegSize, NULL, 
NULL) ) 
t 
// dwRegSize contains the max bytes needed for type detection 
) 
See Also: 


OEMRegistry DetectType() 
ISHELL DetectType() 
ISHELL GetHandler() 
ISHELL Createlnstance(). 
Return to List of functions 
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AEE Object Manager 
Interface 


Object Manager provides an interface to 


* Manage the contexts of BREW objects 
(created in application context and of finite lifetime) that participate in asynchronous 
operations of infinite timeout 


* Facilitate the validation of the objects in asynchronous callbacks 


Why is ObjectMgr needed? 


To illustrate the usage of ObjectMgr, consider the following situation: 


1. An application creates IMedia-based object and calls IMEDIA Play() 


2. IMEDIA Play() in OEM layer implementation calls lower-layer device multimedia 
API that takes a callback function and user data to correlate the transaction. 
Assume we set user data to IMedia object pointer 


3. The callback function gets fired when multimedia task sends events to BREW in 
that task's context. BREW correlates the transaction, identifies the IMedia object, 
saves the event info and requests for a context switch. 


4. When BREW gets scheduled, BREW processes the event info corresponding to 
IMedia object and delivers the event to application If the application is unloaded just 
before step (3) occurs, then IMedia object pointer returned in callback event in is 
invalid. Also, step (3) could occur anytime. 
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ObjectMgr solves the problem 


When the IMedia object is created, the OEM layer implementation must register IMedia object 
with ObjectMgr. ObjectMgr saves object info and returns an opaque object context. This 
context must be used as user data in asynchronous operations. In the callbacks, first query 
ObjectMgr with object context to obtain the object pointer. If the pointer is NULL, then the 
object has been freed either by application or due to application unloading. In this case, drop 
the callback. 


ObjectMgr API: 


AEEObjectMgr Register() Registers the BREW object and returns the 
AEEObjectHandle 


AEEObjectMgr Unregister() Unregisters the BREW object and the object handle is 
no more valid 
AEEObjectMgr GetObject() Given object handle, returns the object pointer 
NOTES: 


* ObjectMgr is never released. It is automatically released by BREW when BREW 
exits. 


List of Header files to be included 

The following header file is required: 
OEMObjectMgr.h 

List of functions 


Functions in this interface include: 


AEEObjectMgr GetObject() 
AEEObjectMgr Register() 
AEEObjectMgr Unregister() 


The remainder of this section provides details for each function. 
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AEEObjectMgr GetObject() 


Description: 
Given object handle, this function retrieves the object. 


























Prototype: 

void * AEEObjectMgr GetObJject (AEEObjectHandle hOb5); 
Parameters: 

hObj Handle of the object 


Return Value: 
NULL: Object does not exist 
Otherwise valid object pointer 


Comments: 
None. 


See Also: 
None. 
Return to List of functions 
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AEEObjectMgr Register() 


Description: 


This function registers a BREW object with the ObjectMgr. ObjectMgr returns an 
opaque context to the caller. 


Prototype: 
int AEEObjectMgr Register 
( 
void * pObject, 
AEEObjectHandle * phObject 
); 























Parameters: 
pObject Object to be registered 
phObject Handle to the object 


Return Value: 
SUCCESS: ObjectMgr cannot allocate handle. 
Otherwise error. 


See Also: 
AEEObjectHandle. 














Return to List of functions 
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AEEObjectMgr Unregister() 


Description: 
This function unregisters the object and calls the caller-registered function, if any. 


























Prototype: 

int AEEObjectMgr Unregister (AEEObjectHandle h0Obj5); 
Parameters: 

hObj Handle of the object 


Return Value: 
SUCCESS: Unregister succeeded 
Otherwise Unregister failed 


Comments: 
The handle should not be used after unregistration. 


See Also: 
None. 
Return to List of functions 
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This interface provides definitions for the 3D graphics engine. Application developers 
need to be aware of possible multiplication overflow when the range of individual 
triangles becomes too large in the rendering process. 


The 3D engine is a fixed-point implementation for rendering three dimensional 
triangles. The graphics model coordinates are in 16.16 format. List of Header files to 
be included 


The following header file is required: 


AEE3D.h 
List of functions 


Functions in this interface include: 


I3D AddRef() 

I3D ApplyModelViewTransform() 
I3D CalcVertexArrayNormal() 
I3D CalcVertexArrayColor() 
I3D ClearFrameBuf() 

I3D GetClipRect() 

I3D GetCoordTransformMode() 
I3D GetCullingMode() 

I3D GetDestination() 

I3D GetFocalLength() 

I3D GetLight() 

I3D GetLightingMode() 

I3D GetMaterial() 

I3D GetModelViewTransform() 
I3D GetRenderMode() 

I3D GetScreenMapping() 

I3D GetTexture() 

I3D GetViewDepth() 

I3D PopMatrix() 

I3D PushMatrix() 

I3D Querylnterface() 

I3D RegisterEventNotify() 

I3D Release() 

I3D RenderTriangleFan() 

I3D RenderTriangles() 


SY 
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I3D RenderTriangleStrip() 

I3D ResetZBuf() 

I3D SetClipRect() 

I3D SetCoordTransformMode() 
I3D SetCullingMode() 

I3D SetDestination() 

I3D SetFocalLength() 

I3D SetLight() 

I3D SetLightingMode() 

I3D SetMaterial() 

I3D SetModelViewTransform() 
I3D SetRenderMode() 

I3D SetScreenMapping() 

I3D SetTexture() 

I3D SetViewDepth() 

I3D StartFrame() 


The remainder of this section provides details for each function. 
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Era I3D Interface 


I3D AddRef() 


Description: 
This function increments the reference count for the 3D graphics class. 


Prototype: 
uint32 I3D AddRef(I3D* pI3D); 
Parameters: 
pIi3D Pointer to a I3D interface whose reference count need to be incremented. 


Return Value: 
The updated reference count. 


Comments: 
None 


See Also: 
I3D Release() 
Return to the List of functions 
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brew. 


I3D Interface 


I3D ApplyModelViewTransform() 


Description: 
General API fo 


r doing model-view transformation given a pointer to a sequence of 


vertex coordinate vectors and number of vertices to be transformed. The Type of 


transformation 


is determined by the transformation mode. The output will update the 


location vectors in the vertex structure. 























Prototype: 
int I3D ApplyModelViewTransform( 
I3D* pI3D, 
ABE3DTLVertex* pVertex, 
AEE3DPoint* pVertexBuf, 
uint32 n); 
Parameters: 
pi3D [in] Pointer to I3D interface. 
pVertex [out] Vertex structure for 3D rendering. 
pVertBuf [in] Pointer to a sequence of coordinates (x,y,z). 
n [in] Number of vertices. 
Return Value: 
SUCCESS on success. 


Error code otherwise. 


Comments: 
None 


See Also: 


AEE3DTLVertex 
Return to the List of functions 
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brew. 


I3D CalcVertexArrayNormal() 


Description: 


I3D Interface 


Calculates the normal components (nx, ny, nz) in the vertex normal array. 


Prototype: 


int I3D CalcVertexArrayNormal 
( 
3D* pme, 








int32 num triangles, 
EE3DPoint* pVertexArray, 

















Pp pe cpa 





) 


Parameters: 
pi3D [in] 
pVertexNormalArray [in/out] 
pVertexIndexArray [in] 
num triangles [in] 
pVertexArray [in] 
Prim type [in] 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
AEE3DPoint 
AEE3DPoint16 
AEE3DPrimitiveType 
AEE3DTLVertex 
Return to the List of functions 
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EE3DPoint16* pVertexNormalArray, 
int16* pVertexIndexArray, 


EE3DPrimitiveType Prim type 


Pointer to I3D interface 

Pointer to vertex normal array 
Pointer to the index vertex array 
Number of triangles 

Pointer to array of vertices 


Type of primitive the Vertex Index Array is 
referring to. (that is, triangles, triangle fan, and 
so on) 


Brevi I3D Interface 


I3D CalcVertexArrayColor() 


Description: 
Calculates the color (rgb) values in the AEE TLVertex array. 


Prototype: 


int I3D CalcVertexArrayColor 


( 
I3D* pI3D, AEESDTLVertex* pVertexArray, 
uintl6* pVertexIndexArray, 














uint32 num vertices, 
AEE3DPoint16* pVertexNormalArray, 
A 

) 

















EE3DPrimitiveType Prim type 





Parameters: 
pi3D [in] Pointer to I3D interface 
pVertexArray [in/out] Pointer to a list of AEE TLVertex 
pVertexIndexArray [in] The index list of vertices 
num vertices [in] Number of vertices 
pVertexNormalArray [in] The list of vertex normals 
Prim type [in] Type of primitive the pVertexList is referring 


to. (that is, Triangles, Triangle fan, and so on) 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
AEE3DPoint 
AEE3DPoint16 
AEE3DPrimitiveType 
AEE3DTLVertex 
Return to the List of functions 
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Era I3D Interface 


I3D ClearFrameBuf() 


Description: 
Clear 3D frame buffer with background color 


Prototype: 

void I3D ClearFrameBuf (13D* pI3D); 
Parameters: 

pi3D [in] Pointer to I3D interface. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Era I3D Interface 


I3D GetClipRect() 


Description: 


This function gets the clipping rectangle. All output parameters will be in terms of 
number of pixels. 














Prototype: 

int I3D GetClipRect (I3D* pI3D, AEERect* pRect); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

pRect [out] Pointer to a AEERect. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
pRect->x: The horizontal coordinate for the top left corner of the rectangle. 
pRect->y: The vertical coordinate for the top left comer of the rectangle. 
pRect->dx: The width of the clipping rectangle. 
pRect->dy: The height of the clipping rectangle. 


See Also: 
I3D SetClipRect() 
AEERect 
Return to the List of functions 


64 


Era I3D Interface 


I3D GetCoordTransformMode() 


Description: 
NOTE: This function is currently not supported. 
This function gets the coordinate transformation type from the graphics context. This 
will indicate which coordinate transformation will be applied before triangles are 
rendered. 


Prototype: 


int I3D GetCoordTransformMode 

( 

I3D* pI3D, 
AEE3DCoordinateTransformType* pType 
); 














Parameters: 
pi3D [in] Pointer to I3D interface. 
pType [out] Pointer to a Coordinate Transformation type. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D SetCoordTransformMode() 
AEE3DCoordinateTransformType. 
Return to the List of functions 
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Eres I3D Interface 


I3D GetCullingMode() 


Description: 
This function gets the culling type. This will indicate which triangles should be 
discarded before they are mapped to the screen. By default, triangles with vertices 
arranged in counterclockwise rotation will be visible. A counterclockwise orientation 
indicates front-facing. A clockwise orientation is considered back facing. 














Prototype: 

int I3D GetCullingMode (I3D* pI3D, AEE3DCullingType* pFacing); 
Parameters: 

pIi3D [in] Pointer to I3D interface. 

pFacing [out] Pointer to culling type. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D SetCullingMode() 
AEES3DCullingType 
Return to the List of functions 
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Eri I3D Interface 


I3D GetDestination() 


Description: 
This function will get the Frame Buffer from I3D. 


Prototype: 

int I3D GetDestination(I3D* pI3D, IBitmap** pFrameBuffer); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

pFrameBuffer [out] IBitmap* pointer for 3D graphics framebuffer. 


Return Value: 
Return SUCCESS on success, 
Otherwise returns error code. 


Comments: 


Currently, I3D only accepts 16 bpp device dependant bitmap (DDB). If pBitmap is not 
16bpp DDB, it will return EUNSUPPORTED. 


See Also: 
I3D SetDestination() 
I3D ClearFrameBuf() 
I3D ResetZBuf() 
IBitmap Interface 
Return to the List of functions 
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Era I3D Interface 


I3D GetFocalLength() 


Description: 
This function gets the focal length. The output range will be within the depth of z-buffer 
(1-32767). 
Prototype: 
int I3D GetFocalLength(I3D* pI3D,uint16* pFocalLength); 
Parameters: 
pi3D [in] Pointer to I3D interface. 
pFocalLength [out] Pointer to a Focal Length 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
The z-buffer is 16 bits in this release. 


See Also: 
I3D SetFocalLength() 
I3D GetViewDepth() 
Return to the List of functions 
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Erevi I3D Interface 


I3D GetLight() 


Description: 
This function will get the lighting properties for the specified light type. 


























Prototype: 

int I3D GetLight (I3D* pI3D, AEE3DLightType type, AEESDLight* light); 
Parameters: 

pi3D [in] Pointer to I3D interface 

type [in] The lighting type 

light [out] The light values 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
AEE3DLight 
AEESDLightType 
I3D GetLightingMode() 
I3D SetLight() 
Return to the List of functions 
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Erevi I3D Interface 


I3D GetLightingMode() 


Description: 
This function will get the lighting mode values. This mode will indicate what lighting is 
enabled for rendering. 














Prototype: 

int I3D GetLightingMode (I3D* pI3D, AEE3DLightingMode* pMode) ; 
Parameters: 

pi3D [in] Pointer to I3D interface 

pMode [out] Pointer to current lighting mode 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
I3D SetLight() 
I3D SetLightingMode() 
AEE3DLight 
AEE3DLightingMode 
AEES3DLightType 
Return to the List of functions 


70 


revi I3D Interface 


I3D GetMaterial() 


Description: 
This function gets the current material. 














Prototype: 

int I3D GetMaterial(I3D* pI3D, AEE3DMaterial* pMaterial); 
Parameters: 

pi3D [in] Pointer to I3D interface 

pMaterial [out] Pointer to the material 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
AEE3DMaterial 
I3D SetMaterial() 
Return to the List of functions 
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Era I3D Interface 


I3D GetModelViewTransform() 


Description: 


This function gets the fixed point transformation matrix. It is copied from the 
ModelViewTransform member of the graphics context structure. 


Prototype: 


int I3D GetModelViewTransform 

( 

I3D* PpI3D, 
AEE3DTransformMatrix* pMatrix 
); 














Parameters: 
pIi3D [in] Pointer to I3D interface. 
pMatrix [out] Pointer to a transformation matrix. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D SetModelViewTransform() 
AEE3DTransformMatrix 
Return to the List of functions 
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Erevi I3D Interface 


I3D GetRenderMode() 


Description: 


This function gets the rendering type. It indicates how the triangle will be filled based 
on the surface color, texel and shading mode. 














Prototype: 

int I3D GetRenderMode (13D* pI3D, AEE3DRenderType* pType); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

pType [out] Pointer to a Render type 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D SetRenderMode() 
AEESDRenderType 
Return to the List of functions 
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Bravo I3D Interface 


I3D GetScreenMapping() 


Description: 


This function gets the fixed-point screen mapping. The scaling part of the output is in 
Q12 format. The translation or shift part is in pixel units. 


Prototype: 


int I3D GetScreenMapping 

( 

I3D* pI3D, 

int32* sx, 

Intõ32* sy; 

int32* shftx, 
int32* shfty 

); 


Parameters: 
pi3D [in] Pointer to I3D interface. 
SX [out] Pointer that will contain the X-scaling in Q12 format. 
sy [out] Pointer that will contain the Y-scaling in Q12 format. 
shftx [out] Pointer that will contain the X-shift in number of pixels. 
shfty [out] Pointer that will contain the Y-shift in number of pixels. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
1 in Q12 = 4096 


Also see: 
Q12 Fixed Point Format 
I3D SetScreenMapping() 
Return to the List of functions 
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Era I3D Interface 


I3D GetTexture() 


Description: 


This function gets the texture of a specific type that is used in 3D rendering. A NULL 
output pointer indicates that no texture image of the given type is being used. 


Prototype: 


int I3D GetTexture 
( 
I3D* pI3D, 
AEE3DTexture* pTexture 
); 

















Parameters: 
pIi3D [in] Pointer to I3D interface. 
pTexture [out] Pointer that contains the texture from the graphics context. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D SetTexture() 
AEE3DTexture 
AEESDTextureType 
Return to the List of functions 


to 


Era I3D Interface 


I3D GetViewDepth() 


Description: 


This function gets the view depth in graphics context. Objects outside the view depth 
will not be rendered. 


Prototype: 
int I3D GetViewDepth (I3D* pI3D, uint1l6* pZ0, uintl6* pZl); 
Parameters: 
pi3D [in] Pointer to I3D interface. 
pZ0 [out] Pointer will contain value of the near view plane (1 <= z0< 21) 
pZ1 [out] Pointer will contain value of the far view plane (Z0 < 21 <=32767) 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
The z-buffer is 16 bit in this release. 


See Also: 
I3D SetViewDepth() 
Return to the List of functions 
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Erevi I3D Interface 


I3D PopMatrix() 


Description: 
This function will pop the current Matrix off the stack. 


Prototype: 

int I3D PopMatrix(I3D* pI3D) 
Parameters: 

pi3D [in] Pointer to I3D interface 


Return Value: 
Returns SUCCESS on success, otherwise returns error code. 


Comments: 
None 


See Also: 
I3D PushMatrix() 
AEE3DMatrixMode 
Return to the List of functions 
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Bravo I3D Interface 


I3D PushMatrix() 


Description: 
This function will push the current Matrix onto the stack. 


Prototype: 

intI3D PushMatrix(I3D* pI3D). 
Parameters: 

pi3D [in] Pointer to I3D interface 


Return Value: 
Returns SUCCESS on success, otherwise returns error code. 


Comments: 
The default max stack size is 32 


See Also: 
I3D PopMatrix() 
AEE3DMatrixMode 
Return to the List of functions 
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Brevi I3D Interface 


I3D QuerylInterface() 


Description: 


This function retrieves a pointer to what you query, according to the input class ID. This 
function can be used to query an extended version of I3D. This supports version 














compatibility. 
Prototype: 

int I3D QueryInterface(I3D* pI3D, AEECLSID id, void** p); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

id [in] A globally unique id to identify the entity (interface or data) that we 
are trying to query. 

p [out] Pointer to the data or interface that we want to retrieve. Ifthe value 
passed back is NULL, the interface or data that we query are not 
available. 

Return Value: 
SUCCESS on success. 
Error code otherwise. 
Comments: 
If “p” passes back a NULL pointer, the data or interface that we query are not 
available. 
See Also: 
None 


Return to the List of functions 
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Brevi I3D Interface 


I3D RegisterEventNotify() 


Description: 


Registers an event callback function to be invoked whenever there is some new event 
or information to report about an asynchronous I3D operation. The application will not 
block on 3D rendering functions. The application developer needs to register a 
callback function to be notified when it is okay to start the next frame and to update the 
display. See the 3D events section to understand what each event means. 

















Prototype: 
int I3D RegisterEventNotify(I3D* pI3D, PFEFNEVENTNOTIFY pfn, void* 
pUser); 
Parameters: 
pi3D [in] Pointer to I3D interface object 
pfn [in] Pointer to the callback function to invoke to notify the application 
of events (NULL to deregister) 
pUser [in] User data to be passed to callback when it is invoked 


Return Value: 
Always returns SUCCESS. 


Comments: 


An event callback function MUST be registered to properly use the 3D engine. It could 
be possible to update the display in the middle of rendering a frame if the user does 
not wait for the approriate event. Check the notified event to make sure it is okay to 
modify data or update the display. YOU MUST USE THIS FUNCTION IN EVERY 
APPLICATION. 


Side Effects: 


If not used the 3D application will not know when to update the display correctly. 


See Also: 
3D Events 
AEE3DEventNotify 
I3D StartFrame() 
Return to the List of functions 
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Era I3D Interface 


I3D Release() 


Description: 
This function decrements the reference count for the 3D graphics object and does 
appropriate cleanup if the reference count reaches zero. 


Prototype: 
uint32 I3D Release (I3D* pI3D); 
Parameters: 
pi3D Pointer to the I3D interface whose reference count needs to be decremented. 


Return Value: 
The updated reference count 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Brevi I3D Interface 


I3D RenderTriangleFan() 


Description: 


Render a triangle fan where each additional vertex defines a new triangle after the 
initial two vertices are defined. The first vertex is part of every triangle. 


Prototype: 


int I3D RenderTriangleFan 

( 

I3D* pI3D, 
AEE3DTLVertex* pVertexArray, 
const uint16* pVertexIndexArray, 
uint32 num of triangles, 
uint32 num of vertices 














Parameters: 
pi3D Pointer to I3D interface 
pVertexArray List of vertices 


pVertexindexArray | Index list to the vertex list 
num of triangles Number of triangles 


num of vertices Number of vertices 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D RenderTriangles() 
I3D RenderTriangleStrip() 
AEE3DTLVertex 
Return to the List of functions 
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Eri I3D Interface 


I3D RenderTriangles() 


Description: 
Render one or more triangles. 


Prototype: 


int I3D RenderTriangles 

( 

I3D* pI3D, 
AEE3DTLVertex* pVertexArray, 
const uinl6* pVertexIndexArray, 
uint32 num of triangles, 
uint32 num of vertices 


); 














Parameters: 
pi3D [in] Pointer to I3D interface 
pVertexArray [in] List of vertices 
pVertexIndexArray [in] List of indicies into the vertex list. Every three of them 
in sequence define a triangle 
num of triangles [in] Number of triangles 
num of vertices [in] Number of vertices 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
I3D RenderTriangleStrip() 
I3D RenderTriangleFan() 
AEE3DTLVertex 
Return to the List of functions 
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brew. 


I3D Interface 


I3D RenderTriangleStrip() 


Description: 


Renders a triangle strip, where each additional vertex defines a new triangle after the 


initial two vertices are defined. 


Prototype: 


int I3D RenderTriangleStrip 


( 
I3D* pI3D, 











AEE3DTLVertex* pVertexArray, 


const uinl6* pVertexIndexArray, 
uint32 num of triangles, 
uint32 num of vertices 





»; Parameters: 
pI3D [in] 
pVertexArray [in] 


pVertexIndexArray [in] 


num of triangles [in] 


num of vertices [in] 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
I3D RenderTriangles() 
I3D RenderTriangleFan() 
AEE3DTLVertex 
Return to the List of functions 


Pointer to I3D interface 
List of vertices 


List of indices into the vertex list. Every three of them in 
sequence define a triangle 


Number of triangles 


Number of vertices 
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revi I3D Interface 


I3D ResetZBuf() 


Description: 
This function resets the Z buffer to the highest depth value (65535 for 16 bit z-buffer). 


Prototype: 

void I3D ResetZBuf (I3D* pI3D); 
Parameters: 

pme [in] Pointer to I3D interface. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Eri I3D Interface 


I3D SetClipRect() 


Description: 


This function sets the clipping rectangle. All input parameters are in pixel units. Objects 
outside the clipping rectangle will not be rendered. The clipping rectangle is the full 
display area by default. 














Prototype: 

int I3D SetClipRect (I3D* pI3D, const AEERect* pRect); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

pRect [in] Pointer to a Clipping Rectangle. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
pRect->x: The horizontal coordinate for the top left corner 
of the clipping rectangle. 
pRect->y: The vertical coordinate for the top left corner 
of the clipping rectangle. 
pRect->dx: The width of the clipping rectangle. 
pRect->dy: The height of the clipping rectangle. 


See Also: 
I3D GetClipRect() 
AEERect 
Return to the List of functions 
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Brevi I3D Interface 


I3D SetCoordTransformMode() 


Description: 
NOTE: This function is currently not supported. 


Set coordinate transformation type. This will indicate which coordinate transformation 
will be applied before triangles are rendered. Model view transformation, projection, 
and screen mapping, all will be applied by default. 


Prototype: 


int I3D SetCoordTransformMode 

( 

I3D* pI3D, 
AEE3DCoordinateTransformType type 
); 














Parameters: 
pIi3D [in] Pointer to I3D interface. 
type [in] Coordinate Transformation type. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D GetCoordTransformMode() 
AEE3DCoordinateTransformType 
Return to the List of functions 
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Era I3D Interface 


I3D SetCullingMode() 


Description: 
Set FRONT or BACK face culling. This will indicate which triangles should be 
discarded before they are rendered. By default, triangles with vertices arranged in 
counter-clock wise rotation will be visible. A counter-clock wise rotation indicates front- 
facing. A clock-wise rotation is considered back-facing. 














Prototype: 

int I3D SetCullingMode (I3D* pI3D, AEE3DCullingType facing); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

facing [in] either FRONT or BACK facing polygons will be culled. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
Default value is BACK FACING 


See Also: 
I3D GetCullingMode() 
AEE3DCullingType 
Return to the List of functions 
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Eru I3D Interface 


I3D SetDestination() 


Description: 
This function will set the Frame Buffer for I3D. 


Prototype: 

int I3D SetDestination(I3D* pI3D, IBitmap* pFrameBuffer); 
Parameters: 

pi3D [in] Pointer to I3D interface 

pFrameBuffer [in] IBitmap pointer for 3D graphics frame buffer 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 


Currently, I3D only accepts 16 bpp device dependant bitmap (DDB). If pBitmap is not 
16bpp DDB, it will return EUNSUPPORTED. 


See Also: 
I3D GetDestination() 
I3D ClearFrameBuf() 
I3D ResetZBuf(), 
IBitmap Interface, 
Return to the List of functions 
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Era I3D Interface 


I3D SetFocalLength() 


Description: 


Set focal length. The input range should be within the depth of z-buffer. Perspective 
division is not performed when focal length=0. 


Prototype: 

int I3D SetFocalLength(I3D* pI3D,uintl6 £); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

f [in] Focal length (1<= f<= 32767) 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D GetFocalLength() 
Return to the List of functions 
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Era I3D Interface 


I3D SetRenderMode() 


Description: 
This function sets the rendering type. It determines how the triangle will be filled based 
on the surface color, texel, and shading mode. A triangle will be shaded with a single 
color (flat-shading) by default. 














Prototype: 

int I3D SetRenderMode (13D* pI3D, AFEE3DRenderType type); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

type [in] Render type 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D GetRenderMode() 
AEESDRenderType 
Return to the List of functions 
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Eres I3D Interface 


I3D SetScreenMapping() 


Description: 


Set fixed-point screen mapping matrix. The scaling part of input is in Q12 Fixed Point 
Format. The translation part is in number of pixels. Input range is not checked 


Prototype: 


int I3D SetScreenMapping 

( 

I3D* pI3D, 

int32 sx, 

1nt32 sv; 

int32 shftx, 

int32 shfty 

); 


Parameters: 
pi3D [in] Pointer to I3D interface. 
sx [in] X-scaling in Q12 format (unit scaling = 4096) 
Sy [in] Y-scaling in Q12 format (unit scaling = 4096) 
shftx [in] X-shift (in pixel). 
shfty [in] Y-shift (in pixel). 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
Q12 Fixed Point Format 
I3D GetScreenMapping() 
Return to the List of functions 


92 


Era I3D Interface 


I3D SetTexture() 


Description: 


Set texture to be used in 3D rendering. A NULL input pointer indicates that the 
corresponding texture image will not be used. Texture is initialized to NULL by default. 


Prototype: 


int I3D SetTexture 
( 
I3D* pI3D, 
AEE3DTexture* pTexture 
); 

















Parameters: 
pi3D [in] Pointer to I3D interface. 
pTexture [in] Pointer to a texture object. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D GetTexture() 
AEE3DTexture 
AEESDTextureType 
Return to the List of functions 
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Era I3D Interface 


I3D SetViewDepth() 


Description: 


Set view depth to be used in graphics context. Objects outside the view depth will not 
be rendered. The default view depth is the entire range of the z-buffer (0-65535). 


Prototype: 

int I3D SetViewDepth (I3D* pI3D,uintl6 z0,uint1l6 z1); 
Parameters: 

pi3D [in] Pointer to I3D interface. 

zO [in] The near view plane (1 <= z0 < 21) 

z1 [in] The far view plane (z0 < z1 < 32767 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
The z-buffer is 16 bit. The default view depth is set to (1,2048). 


See Also: 
I3D GetViewDepth() 
Return to the List of functions 
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Eres I3D Interface 


I3D SetLight() 


Description: 
This function will set the lighting properties for the specified light type. 














Prototype: 
int I3D SetLight (I3D* pI3D, AEE3DLight plight); 
Parameters: 
pi3D [in] Pointer to I3D interface. 
plight [in] Pointer to a light. 


Return Value: 
Return SUCCESS on success. 
Otherwise returns error code. 


Comments: 
None 


See Also: 
AEE3DLight 
I3D SetLightingMode() 
I3D GetLight() 
Return to the List of functions 
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revi I3D Interface 


I3D SetLightingMode() 


Description: 


This function will set the lighting mode. This mode will indicate what lighting is enabled 
for rendering. 














Prototype: 
int I3D SetLightingMode (I3D* pI3D, AEE3DLightingMode mode) ; 
Parameters: 
pi3D [in] Pointer to I3D interface 
mode [in] The lighting mode 


Return Value: 
Return SUCCESS on success 
Otherwise returns error code 


Comments: 
None 


See Also: 
AEE3DLight 
I3D SetLight()() 
I3D GetLightingMode() 
Return to the List of functions 
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I3D SetMaterial() 


Description: 
This function sets the current material properties. 














Prototype: 

int I3D SetMaterial(I3D* pI3D, AEE3DMaterial* pMaterial); 
Parameters: 

pi3D [in] Pointer to I3D interface 

pMaterial [in] Pointer to the material 


Return Value: 
SUCCESS on success 
Error code otherwise 


Comments: 
None 


See Also: 
AEE3DMaterial 
I3D GetMaterial() 
Return to the List of functions 
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I3D SetModelViewTransform() 


Description: 
Set fixed point transformation matrix. The input matrix is assumed to have the correct 
Q-factor. It is copied to the Model View Transform Matrix of the graphics context 
structure. Range of input is not checked. 


Prototype: 


int I3D SetModelViewTransform 
( 
I3D* pI3D, 
const AEE3DTransformMatrix* pMatrix 
); 














Parameters: 
pi3D [in] Pointer to I3D interface. 
pMatrix [in] Pointer to a Model-view transformation matrix. 


Return Value: 
SUCCESS on success. 
Error code otherwise. 


Comments: 
None 


See Also: 
I3D GetModelViewTransform() 
AEE3DTransformMatrix 
Return to the List of functions 
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I3D Startframe() 


Description: 
This function will not block but will run asynchronous. It will tell the 3D graphics engine 
to start processing and rendering the current frame. 


Prototype: 

int I3D StartFrame (I3D* po); 
Parameters: 

po [in] Pointer to I3D interface. 


Return Value: 
SUCCESS: Command accepted. 
EFAILED: General failure. 
EBADPARM: Bad parm is passed. 
ENOMEMORY: Not enough memory. 


Comments: 


MUST register an event callback function to properly use the 3D engine. It could be 
possible to update the display in the middle of rendering a frame if the user does not 
wait for the approriate event. Check the notified event to makes sure it is okay to modify 
data or update the display. YOU MUST USE THIS FUNCTION IN EVERY 
APPLICATION. 


Side Effects: 


If NOT called the 3D graphics engine will not know when to start rendering the current 
frame. THIS FUNCTION MUST BE CALLED TO START THE RENDERING ENGINE. 


See Also: 
I3D RegisterEventNotify() 
3D Event types 
Return to the List of functions 
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13DUtil Interface 


This interface provides definitions for the 3D graphics Utility made available by the AEE to the 
application developers. This is a standard header file that must be included by all applications 
using I3DUtil interfaces. 


These utility functions provide the developer with simplified operations to obtain the model- 
view transformation matrices and unit vectors. 


NOTE: ALL I3DUtil functions are in Q12 format. Parameters are expected to be in Q12 fixed 
point format. 


List of Header files to be included 


The following header file is required: 


AEES3DUtil.h 


List of functions 
Functions in this interface include: 


I3DUtil AddRef() 

I3DUtil cos() 

I3DUtil GetRotateMatrix() 
I3DUtil GetRotateVMatrix() 
I3DUtil GetViewTransformMatrix() 
I3DUtil GetUnitVector() 
I3DUtil MatrixMultiply() 
I3DUtil QuerylInterface() 
I3DUtil Release() 

I3DUtil SetldentityMatrix() 
I3DUtil SetTranslationMatrix() 
I3DUtil sin() 

I3DUtil sgrt() 


The remainder of this section provides details for each function. 
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I3DUtil AddRef() 


Description: 
This function increments the reference count of the |3DUtil Interface object, allowing 
the object to be shared by multiple callers. The object is freed when the reference 
count reaches O (zero). 


Prototype: 

uint32 I3DUtil AddRef(T3DUtil* pI3DUtil) 
Parameters: 

pI3DUtil Pointer to the I3DUtil Interface object. 


Return Value: 
Incremented reference count for the object. 


Comments: 
A valid object returns a positive reference count. 


See Also: 
I3DUtil Release() 
Return to the List of functions 
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brew. 
I3DUtil cos() 
Description: 
This function computes the cosine. 
Prototype: 
int32 I3DUtil cos(I3DUtil* pI3DUtil, int32 angle) 
Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
angle [in] Q12 format (Pl-=2048). 


Return Value: 
Returns the cosine of the angle. 


Comments: 
None 


See Also: 
Q12 Fixed Point Format 
Return to the List of functions 
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|3DUtil GetRotateMatrix() 


Description: 
This function computes the transformation matrix for a rotation about x, y, or z-axis. 


Prototype: 
int I3DUtil GetRotateMatrix 
( 
I3DUtil* pI3DUtil, 
int32 angle, 
EE3DTransformMatrix* pMatrixOut, 
EE3DRotateType axis 




















=>» 


Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
angle [in] Rotation angle in Q12 format. 
pMatrixOut [out] Pointer to the resulting transformation matrix. 
axis [in] Axis to do rotation around. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
In respect to the angle (PI = 2048). 


See Also: 
Q12 Fixed Point Format 
AEE3DTransformMatrix 
AEE3DRotateType 
Return to the List of functions 
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I3DUtil GetRotateVMatrix() 


Description: 


This function computes the transformation matrix for a rotation about a given vector 
from origin. 


Prototype: 


int I3DUtil GetRotateVMatrix 

( 

I3DUtil* pI3DUtil, 

const AEE3DPoint* pVector, 

int32 angle, 
AEE3DTransformMatrix* pMatrixOut 
); 


























Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
pVector [in] Pointer to vector originated from origin for the rotation in Q12 
format. 
angle [in] Rotation angle in Q12 format (Pl=2048). 
pMatrixOut [out] Pointer to the resulting transformation matrix. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 
Q12 Fixed Point Format 
AEE3DPoint 
AEE3DTransformMatrix 
Return to the List of functions 
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13DUtil Interface 


I3DUtil GetViewTransformMatrix() 


Description: 


This function computes the fixed point transformation matrix for a given position, look- 
at-direction, and up-direction. Each directional vector is given as a 3D point or vector 


in Q12 format. 


Prototype: 


int I3DUtil GetViewTransformMatrix 


( 


I3DUtil* 


const AE 
const AE 
const AE 














); 


Parameters: 
pI3DUtil 
pPosition 
pLook 


pUp 
pMatrixOut 


Return Value: 





pI3DUtil, 


E3DPoint* pPosition, 




















E3DPoint* pLook, 
E3DPoint* pUp, 





[in] 
[in] 
[in] 
[in] 


AEE3DTransformMatrix* pMatrixOut 


Pointer to I3DUtil interface. 
Pointer to positional vector of the viewer. 
Pointer to directional vector of the viewing direction. 


Pointer to directional vector for the up-direction. 


[out] Pointer to the resulting transformation matrix. 


SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 


Q12 Fixed Point Format 


AEE3DPoint 


AEE3DTransformMatrix 
Return to the List of functions 
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|3DUtil GetUnitVector() 


Description: 


This function computes the unit vector (dst) of a source vector (src). The resulting 
vector is Q12. 


Prototype: 


int I3DUtil GetUnitVector 
(I3DUtil* pI3DUtil, 
const AEE3DPoint* pSrc, 
AEE3DPoint* pDst 
) 


























Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
pSrc [in] Pointer to source vector. 
pDst [out] Pointer to resulting unit vector. 


Return Value: 
Return SUCCESS on success. 
Otherwise returns error code. 


Comments: 
None 


See Also: 
AEE3DPoint 
Q12 Fixed Point Format 
Return to the List of functions 
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I3DUtil MatrixMultiply() 


Description: 


This function multiplies two fixed point matrices. The multiplication is made using the 
equation: 


MaxtrixOut = MatrixOut * MatrixIn 


Prototype: 


int I3DUtil MatrixMultiply 
( 
I3DUtil* pI3DUtil, 
AEE3DTransformMatrix* pMatrixOut, 
const AEE3DTransformMatrix* pMatrixIn 
Di; 























Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
pMatrixOut [in/out] Left multiplicant and the resulting matrix. 
pMatrixln [in] Right mutiplicant. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 
Q12 Fixed Point Format 
AEE3DTransformMatrix 
Return to the List of functions 
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I3DUtil QueryInterface() 


Description: 
This function asks an object for another API contract from the object in question. 


Prototype: 

int I3DUtil QueryInterface 
( 
I3DUtil * pI3DUtil, 
AEECLSID idReg, 
void * * ppo 


) 














Parameters: 
pI3DUtil [in] Pointer to the I3DUStil Interface object. 
idReg [in] Requested ClassiD exposed by the object. 
ppo [in/out] Returned object. Filled by this function. 


Return Value: 
SUCCESS, interface found. 
ENOMEMORY, insufficient memory. 
ECLASSNOTSUPPORT, requested interface is unsupported. 


Comments: 
* If*ppo is an interface pointer, then the pointer in *ppo is set to the new interface (with 
refcount incremented), or NULL if the ClasslD is not supported by the object. 


* If*ppo is a data structure pointer, then *ppo is setto the internal data represented by 
the classID or set to NULL if classID is not supported by the object. 


See Also: 
None 
Return to the List of functions 
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I3DUtil Release() 


Description: 
This function decrements the reference count of the |3DUtil Interface object. The object 
is freed ffom memory and is no longer valid when the reference count reaches O (zero). 


Prototype: 

uint32 I3DUtil Release (I3DUtil * pI3DUtil) 
Parameters: 

pI3DUtil Pointer to the |3DUtil Interface object. 


Return Value: 
Decremented reference count for the object. 
O (zero) if the object has been freed and is no longer valid. 


Comments: 
None 


See Also: 
[3DUtil AddRef() 
Return to the List of functions 
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[3DUtil SetldentityMatrix() 


Description: 
Set the rotation part (3x3) of the transformation matrix to the identity matrix in Q12 
format. 


The transformation matrix will set to: 
(4096,0,0,0, 
0, 4096, 0,0, 
0, 0, 4096, 0 | 


Prototype: 


int I3DUtil SetIdentityMatrix 
( 
I3DUtil* pI3DUtil, 
AEE3DTransformMatrix* pMatrixOut 
) 














Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
pMatrixOut [out] Pointer to the resulting matrix. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 
Q3D File Format 
AEE3DTransformMatrix 
Return to the List of functions 


110 


Erevi 13DUtil Interface 


I3DUtil SetTranslationMatrix() 


Description: 


This function sets the translation part of the transformation matrix for a given 
translation vector in Q12 Fixed Point Format. 


Prototype: 


int I3DUtil SetTranslationMatrix 


3DUtil* pI3DUtil, 
EE3DPoint* pVector, 
EE3DTransformMatrix* pMatrixOut 




















-25PHA 


=. 


Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
pVector [in] Pointer to the translation vector in Q12 Fixed Point Format. 
pMatrixOut [in&out] Pointer to the resulting matrix. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 
Q12 Fixed Point Format 
AEE3DPoint 
AEE3DTransformMatrix 
Return to the List of functions 
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brew. 
13DUtil sin() 
Description: 
This function computes the sine. 
Prototype: 
int32 I3DUtil sin(I3DUtil* pI3DUtil, int32 angle) 
Parameters: 
pI3DUtil [in] Pointer to I3DUtil interface. 
angle [in] Q12 format (Pl=2048). 


Return Value: 
Returns the sine of the angle. 


Comments: 
None 


See Also: 
Q12 Fixed Point Format 
Return to the List of functions 


112 


Era 13DUtil Interface 


I3DUtil sart() 


Description: 
This function computes the square root of the input parameter number. 


Prototype: 

uint32 I3DUtil sgrt (I3DUtil* pI3DUtil, uint32 number); 
Parameters: 

pI3DUtil Pointer to I3DUtil interface. 

number input parameter 


Return Value: 
Returns the square root of the number. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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|3DModel Interface 


This interface provides definitions for 3D graphics models made available to the application 
developers. A standard header file must be included by all applications using the |3DModel 
interfaces. 


The |3DModel provides high-level APIs for users to draw a structured group of triangles. 


The reserved unique ClassID for |3DModel is defined to be AEECLSID 3DMODEL. 


List of Header files to be included 


The following header files are required for |3DModel 


AEE3DModel.h 
List of functions 


Functions in this interface include: 


|3DModel AddRef() 

I3DModel Draw() 

3DModel GetModelData() 
|3DModel GetModelVertexList() 
I3DModel Load() 

/3DModel QuerylInterface() 
I3DModel Release() 

3DModel SetTextureTbI() 
I3DModel SetSegmentMVT() 


The remainder of this section provides details for each function. 
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|3DModel AddRef() 


Description: 
This function increments the reference count of the |3DModel Interface object, allowing 
the object to be shared by multiple callers. The object is freed when the reference 
count reaches O (zero). 


Prototype: 

uint32 I3DModel AddRef (I3DModel* pI3DModel) 
Parameters: 

pi3DModel Pointer to the |3DModel Interface object. 


Return Value: 
Incremented reference count for the object. 


Comments: 
A valid object returns a positive reference count. 


See Also: 
I3DModel Release() 
Return to the List of functions 
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I3DModel Draw() 


Description: 
This function will draw a 3D model. The 3D model must be in the 3D model structure. 


Prototype: 

int I3DModel Draw (13DModel* pI3DModel, I3D* pI3D); 
Parameters: 

pi3DModel [in] Pointer to |3DModel interface. 

pi3D [in] Pointer to I3D interface. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 


The lower-level function called in this routine is I3D RenderTriangles. If lighting mode 
is set to NONE then you can replace the AEE3DVertex list contained in the model 
structure with the AEE3DTLVertex list, in which color has been defined per vertex. 


See Also: 
Q3D File Format 
AEE3DVertex 
AEE3DModelData 
Return to the List of functions 
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|3DModel GetModelData() 


Description: 
This function will get the model information for an |3DModel instance. 


Prototype: 

int I3DModel GetModelData 
( 
I3DModel* pI3DModel, 
AEE3DModelData** pModel out 
) 














Parameters: 
pi3DModel [in] Pointer to |3DModel interface. 
pModel out [out] Address of a pointer to a model structure. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 
AEE3DModelData 
Q3D File Format 
Return to the List of functions 
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|3DModel GetModelVertexList() 


Description: 
This function will get the vertex list stored in an |3DModel instance. 


Prototype: 


int I3DModel GetModelVertexList (1I3DModel* pI3DModel, AEE3DVertex** 
pVertexList out); 














Parameters: 
pi3DModel [in] Pointer to |3DModel interface. 
pVertexList out [out] Address of a pointer to a vertex list. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
None 


See Also: 
Q3D File Format 
AEE3DVertex 
Return to the List of functions 
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I3DModel Load() 


Description: 
This function will load a 3D model. The 3D model must be in the Q3D file format. 


Prototype: 

int I3DModel Load (13DModel* pI3DModel, const char* pFilename); 
Parameters: 

pi3DModel [in] Pointer to |3DModel interface. 

pFilename [in] File name string. 


Return Value: 
SUCCESS on success. 
Error code, otherwise. 


Comments: 
The internal model is only allocated when |3DModel Load is called. 


See Also: 
Q3D File Format 
AEE3DModelData 
AEE3DVertex 
I3DModel GetModelData() 
|3DModel GetModelVertexList() 
Return to the List of functions 
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|3DModel Querylnterface() 


Description: 
This function asks an object for another API contract from the object in question. 


Prototype: 

int I3DModel QueryInterface 
( 
I3DModel* pI3DModel, 
AEECLSID idReg, 
voild** ppo 


) 














Parameters: 
pi3DModel [in] Pointer to the |3DModel Interface object. 
idReqg [in] Requested ClassiD exposed by the object. 
ppo [in/out] 'Returned object. Filled by this function. 


Return Value: 
SUCCESS, interface found. 
ENOMEMORY, insufficient memory. 
ECLASSNOTSUPPORT, requested interface is unsupported. 


Comments: 
* If*ppo is an interface pointer, then the pointer in *ppo is set to the new interface (with 
refcount incremented), or NULL if the ClasslD is not supported by the object. 


* If*ppo is a data structure pointer, then *ppo is set'to the internal data represented by 
the classID or set to NULL if classID is not supported by the object. 


See Also: 
None 
Return to the List of functions 
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I3DModel Release() 


Description: 
This function decrements the reference count of the |3DModel Interface object. The 
object is freed from memory and is no longer valid when the reference count reaches 
O (zero). 


Prototype: 


uint32 I3DModel Release (13DModel* pI3DModel) 


Parameters: 
pl3DModel Pointer to the |3DModel Interface object. 


Return Value: 
Decremented reference count for the object. 
O (zero), If the object has been freed and is no longer valid. 


Comments: 
None 


See Also: 
I3DModel AddRef() 
Return to the List of functions 
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|3DModel SetTextureTbI() 


Description: 
This function will set the texture table in a model. 


Prototype: 

int I3DModel SetTextureTb1l 
( 
13DModel* p13DModel, 
AEE3DTexture* pTexture, 
unit1l6 index 


) 

















Parameters: 
p13DModel [in] Pointer to |3DModel instance 
pTexture [in] Pointer to a texture 
index [in] Index for the model's texture table 


Return Value: 
SUCCESS, EFAILED. 


Comments: 
None 


See Also: 
AEE3DTexture 
Return to the List of functions 
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|3DModel SetSegmentMVT() 


Description: 
This function will set the texture table in a model. 


Prototype: 


int I3DModel SetSegmentMVT (13DModel* p13DModel, AEE3DTransformMatrix* 
trans, intl6 index) 














Parameters: 
p13DModel [in] Pointer to |3DModel instance 
trans [in] Pointer to a transformation matrix 
index [in] Segment index -1 will set all segments using this transformation 


Return Value: 
SUCCESS, EFAILED. 


Comments: 
None 


See Also: 
AEE3DModelData 
AEE3DTransformMatrix 
Return to the List of functions 


123 


brew. 
IBitmap Interface 


This interface manipulate bitmaps. Each IBitmap instance represents a bitmap. IBitmap is an 
interface with multiple implementations. Device-independent bitmaps (DIB) created with 
IDISPLAY CreateDIBitmap() are one class, and bitmaps that represent the handset's display 
are another class. While both classes implement the IBitmap interface, each has different 
capabilities. Both DIBs and display bitmaps can be used in blit operations. Display bitmaps 
support all drawing operations, but DIBs do not generally support drawing, and return 
EUNSUPPORTED from most functions. All functions that return an error code can potentially 
return EUNSUPPORTED. Users should be prepared for all types of error codes. 


List of Header files to be included 


The following header file is required: 


AEEBitmap.h 
List of functions 


Functions in this interface include: 


IBITMAP AddRef() 

IBITMAP BltIn() 

IBITMAP BKOut() 

IBITMAP CreateCompatibleBitmap() 
IBITMAP DrawHScanline() 
IBITMAP DrawPixel() 

IBITMAP FillRect() 

IBITMAP Getlnfo() 

IBITMAP GetPixel() 

IBITMAP GetTransparencyColor() 
IBITMAP NativeToRGB() 
IBITMAP Querylnterface() 
IBITMAP Release() 

IBITMAP RGBToNative() 
IBITMAP SetPixels() 

IBITMAP SetTransparencyColor() 


The remainder of this section provides details for each function. 
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IBITMAP. AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IBITMAP Release() 
Return to the List of functions. 
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IBITMAP. BltIn() 


Description: 


This function performs a bit-block transfer of the data corresponding to a rectangle of 
pixels from the specified source bitmap into this bitmap. Each pixel in the source is 
associated with a corresponding pixel in the destination. A logical operation is 
performed on each pair of source and destination pixels, and the result is written over 
the destination pixel. 


Prototype: 


int IBITMAP BltIn 


( 
IBitmap * pIBitmap, 








ant xDst, 

int yDst, 

int dx, 

int dy, 

IBitmap *pSrc, 
int xSrc, 

int ySrc, 
AEERaster0Op rop 








) 


Parameters: 

pIBitmap [in] Pointer to the IBitmap interface object into which the bit-block 
transfer needs to be done. 

xDst [in] Specifies the x-coordinate of the upper left corner of the 
destination rectangular area. 

yDst [in] Specifies the y-coordinate of the upper left corner of the 
destination rectangular area. 

dx [in] Specifies the width of the destination and source rectangles. 
Negative values are treated as zero. 

dy [in] Specifies the height of the destination and source rectangles. 
Negative values are treated as zero. 

pSrc [in] Pointer to another IBitmap interface that represents the source 
bitmap. 

xSrc [in] Specifies the x-coordinate of the upper left corner of the source 
bitmap from where the bit-block transfer must begin. 

ySrc [in] Specifies the y-coordinate of the upper left corner of the source 
bitmap from where the bit-block transfer must begin. 

rop [in] Specifies the raster operation that is used while doing the bit- 


block transfer. 
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Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EUNSUPPORTED, if a non-supported raster operation is specified. 


Other error code, if the operation is not supported. This might be due to the format 
of the source bitmap or the type of raster operation that was requested or a 
combination of the two. 


Comments: 
When either dx or dy is negative, nothing is written to the destination bitmap. The 
rectangles are treated as empty. 


It is legal for all or part of the source or destination rectangles that fall outside the 
corresponding bitmap bounds, to include negative coordinates. 


When parts of the source or destination rectangles exceed a bitmap's bounds, they are 
clipped. Clipping will not affect the mapping from source to destination of any unclipped 
portions, and will not result in an error code, even when everything is clipped. 


When the width and height of the source bitmap are not known, to blit the entire bitmap, 
very large values can be supplied for dx and dy, and clipping will limit the rectangle to 
the size of the source. 


The source bitmap may or may not be the same format as the destination bitmap, but 
not all source formats are necessarily supported. 


See Also: 
AEERasterOp 
IBITMAP BKOut() 
Return to the List of functions 
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IBITMAP BItOut() 


Description: 
Perform a bit-block transfer from this bitmap into a specified destination bitmap. Users 
would not normally call this function directly. Instead, the destination bitmap's 
IBITMAP BltIn() member function should be called, because that will succeed in more 


cases. 


Prototype: 


int IBITMAP BltOut 


( 


IBitmap Interface 


IBitmap * pIBitmap, 


1 


HEHEHE 


Parameters: 


pIBitmap 


xDst 


yDst 


dx 
dy 
pDst 


xSrc 


ySrc 


rop 














itmap *pDst, 


nt xDst, 
nt yDst, 
nt dx, 
nt dy, 

B 

nt xSre, 
nt ySrc, 


EERaster0p rop 


[in] 
[in] 
[in] 
[in] 
[in] 
[in] 
[in] 
[in] 


[in] 


Pointer to the IBitmap Interface object from which the bit-block 
transfer needs to be done. 


Specifies the x-coordinate of the upper left corner of the 
destination rectangular area. 


Specifies the y-coordinate of the upper left corner of the 
destination rectangular area. 


Specifies the width of the destination rectangle. 
Specifies the height of the destination rectangle. 


Pointer to another IBitmap interface that represents the 
destination bitmap. 


Specifies the x-coordinate of the upper left corner of the source 
bitmap from where the bit-block transfer must begin. 


Specifies the y-coordinate of the upper left corner of the source 
bitmap from where the bit-block transfer must begin. 


Specifies the raster operation that is used while doing the bit-block 
transfer. 
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Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EUNSUPPORTED, if a non-supported raster operation. 
Other implementation-specific error codes 


Comments: 


There is no need to call this function except from the implementation of 

IBITMAP BltIn(). IBITMAP BItOut() exists to help IBITMAP Bltin(). IBITMAP BltIn() 
will delegate to the source bitmap's IBITMAP BItOut() when the destination does not 
support the operation and the bitmaps are of different classes. In this manner, both 
classes have the opportunity to perform the operation, and it will succeed as long as 
either class supports it. Note that IBITMAP BItOut() cannot delegate likewise to 
IBITMAP BltIn(), because that would lead to infinite recursion. 


See Also: 
AEERasterOp 
IBITMAP BltIn() 
Return to the List of functions 
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IBITMAP CreateCompatibleBitmap() 


Description: 


This function creates a new bitmap compatible with this bitmap interface (the first 
parameter). Compatible means having equivalent pixel sizes and the same mapping 
between pixel values (native colors) and RGB values. Width and height do not affect 
compatibility. A blit operation involving two compatible bitmaps is reasonably fast, 
because it does not need to perform complex translations of pixel data. Being a 
common case, this type of operation is typically highly optimized. Also, copies between 
compatible bitmaps do not result in the loss of any color information. A compatible 
bitmap will generally support all the same drawing operations that the original bitmap 
supporis. 


Prototype: 


int IBITMAP CreateCompatibleBitmap 
( 
IBITMAP *pIBitmap, 
IBitmap **ppIBitmap, 
uintil6 w, 


uintl6 h 
) 
Parameters: 
pIBitmap [in] Pointer to the current bitmap interface. 


ppiBitmap | [out] Pointer to the interface of new bitmap that has the same format 
of the current bitmap. 

W [in] Width of the new bitmap. 

h [in] Height of the new bitmap. 


Return Value: 
SUCCESS, if the function executed correctly. 
Error code, if otherwise. 
ENOMEMORY, if there was not enough memory for the operation. 
Other implementation-specific error codes. 


Comments: 
The created bitmap inherits the transparency color from the bitmap it was created from. 


See Also: 
None 
Return to the List of functions 
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IBITMAP DrawHScanline() 


Description: 
This function draws a horizontal line. 


Prototype: 
int IBITMAP DrawHScanline 

( 
IBitmap *pIBitmap, 
unsigned y, 
unsigned xMin, 
unsigned xMax, 
NativeColor color, 

AEERaster0Op rop 

) 














Parameters: 


plBitmap [in] Pointer to the IBitmap Interface object to be used to draw the 
horizontal line. 


y [in] Y-coordinate of the line. 

xMin [in] X-coordinate of the left end of the line. 

xMax [in] X-coordinate of the right end of the line. 

color [in] Specifies the color to be used to draw the line. This is a native 
color, which is obtained using IBITMAP RGBToNative(). 

rop [in] Specifies the raster operation that is used to draw the line. Only 


AEE RO COPY and AEE RO XOR are valid. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EBADPARM, if raster operation is invalid. 
Other implementation-specific error codes 


Comments: 
None 


See Also: 
AEERasterOp 
Return to the List of functions 
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IBITMAP. DrawPixel() 


Description: 
This function draws a single pixel in the bitmap. 


Prototype: 
int IBITMAP DrawPixel 

( 
IBitmap *pIBitmap, 
unsigned x, 
unsigned y, 
NativeColor color, 

AEERaster0Op rop 

) 














Parameters: 
pliBitmap [in] Pointer to the IBitmap Interface to which the pixel will be drawn. 
x [in] X-coordinate of the pixel. 
y [in] Y-coordinate of the pixel. 
color [in] Specifies the color to be used to draw the pixel. This is a native 
color, which is obtained using IBITMAP RGBToNative(). 
rop [in] Specifies the raster operation that is used to draw the pixel. Only 


AEE RO COPY and AEE RO XOR are valid. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EBADPARM, if raster operation is invalid. 
Other implementation-specific error codes 


Comments: 
Ifx or y is outside the bounds of the bitmap, nothing is drawn, and SUCCESS is 
returned. 


See Also: 
AEERasterOp 
IBITMAP GetPixel() 
IBITMAP SetPixels() 
Return to the List of functions 
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IBITMAP  FillRect() 


Description: 
This function draws a solid rectangle of the specified color. 


Prototype: 


int IBITMAP FillRect 
( 
IBitmap *pIBitmap, 
const AEERect *prc, 
NativeColor color, 

AEERaster0Op rop 

) 


























Parameters: 
pIBitmap [in] Pointer to the IBitmap Interface object to be used to fill the rectangle. 
pre [in] A valid pointer to a rectangle that needs to be filled with the specified 
color. 
color [in] Specifies the color to be used to fill the rectangle. This is a native 
color, which is obtained using IBITMAP RGBToNative(). 
rop [in] Specifies the raster operation that is used while drawing the 


rectangle. Only AEE RO COPY and AEE RO XOR are valid. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EBADPARM, if raster operation is invalid. 
Other implementation-specific error codes 


Comments: 


The pre parameter must be a valid pointer. Any portions of the rectangle that fall 
outside the bitmap's bounds are silently ignored (no error is generated). 


See Also: 
AEERasterOp 
Return to the List of functions 
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IBITMAP Getinfo() 


Description: 
This function retrieves the dimension of the bitmap. 


Prototype: 
int IBITMAP GetInfo 
( 
IBitmap * pIBitmap, 
AEEBitmapInfo * pinfo, 
int nSize 


) 














Parameters: 
plBitmap [in] Pointer to the IBitmap Interface. 
pinfo [out] Pointer to AEEBitmaplInfo, which contains the width, height, color 
depth, and so on. 
nSize [in] Set to the sizeof(AEEBitmaplnfo) in the current version. The 


AEEBitmaplInfo structure may grow over time. This field allows 
backward compatibility. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EUNSUPPORTED, if the size is not recognized by the bitmap 


Comments: 


This function should always succeed when nSize is equal to sizeof(AEEBitmaplInfo), 
and when pinfo is a valid pointer. 


See Also: 
AEEBitmaplInfo 
Return to the List of functions 


134 


Erevi IBitmap Interface 


IBITMAP. GetPixel() 


Description: 
This function retrieves the value of the specified pixel. 


Prototype: 
int IBITMAP GetPixel 
( 
IBitmap *pIBitmap, 
unsigned x, 
unsigned y, 
NativeColor *pColor 


) 


Parameters: 
plBitmap [in] Pointer to the IBitmap interface from which the pixel value is 
retrieved. 
x [in] X-coordinate of the pixel. 
y [in] Y-coordinate of the pixel. 
pColor [out] Color of the specified pixel. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EBADPARM, if the coordinate is out of range. 
EUNSUPPORTED, if the operation is not supported. 
Other implementation specific-error codes. 


Comments: 
None 


See Also: 
IBITMAP SetPixels() 
Return to the List of functions 


135 


Breu IBitmap Interface 


IBITMAP GetTransparencyColor() 


Description: 


This function gets the current transparency color of the bitmap. This is used when this 
bitmap is the source bitmap of a transparent bit blit operation. 


Prototype: 


int IBITMAP GetTranparencyColor 
( 
IBITMAP *pMe, 
NativeColor *pColor 


) 


Parameters: 
pMe [in] Pointer to the current bitmap interface. 
pColor [out] Transparency color. 


Return Value: 
SUCCESS, if the function executed correctly. 
Error code, if otherwise. 
EBADPARM, if pColor is NULL. 
EUNSUPPORTED, if the operation is not supported. 
Other implementation-specific error codes 


Comments: 
The transparency color is a NativeColor value, not an RGBVAL. 


See Also: 
IBITMAP BltIn() 
IBITMAP BKOut() 
IBITMAP SetTransparencyColor() 
Return to the List of functions 
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IBITMAP. Native ToRGB() 


Description: 
This function obtains the RGB definition of a NativeColor value, in RGBVAL format. 


Each valid NativeColor corresponds to an RGB value. The mapping of NativeColor 
values is a property of the bitmap. 


Prototype: 

RGBVAL IBITMAP NativeTORGB (IBitmap *pIBitmap, NativeColor clr) 
Parameters: 

plBitmap [in] Pointer to the IBitmap Interface. 

clr [in] Native color value. 


Return Value: 
The corresponding RGBVAL. 


Comments: 


If the NativeColor provided is not associated with a specific RGB value, the return 
value from this function is undefined. 


See Also: 
NativeColor 
RGBVAL 
IBITMAP RGBToNative() 
Return to the List of functions 
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IBITMAP Querylnterface() 


Description: 


This function retrieves a pointer to an interface conforming to the definition of the 
specified ClasslD. This can be used to query for extended functionality, like future 
versions or proprietary features. Upon a successful query, the interface is returned. 
The caller is responsible for calling Release() at some point in the future. One 
exception is when the pointer returned is not an interface pointer. In that case, the 
memory will share the lifetime of the object being queried, and the returned pointer will 
not be used to free or release the object. 














Prototype: 
int IBITMAP QueryInterface (IBitmap *pIBitmap, AEECLSID id, void **p); 
Parameters: 
pIBitmap [in] Pointer to the IBitmap interface. 
id [in] A globally unique id to identify the entity (interface or data) 
being queried. 
p [out] Pointer to the data or interface to be retrieved. If the value 
passed back is NULL, the queried interface or data is not 
available. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 


Comments: 


Many bitmaps support the IDIB interface (class id: AEECLSID DIB), which contains 
public data that allows the caller to directly access the bitmap data. Only bitmaps with 
internal formats that conform to one of the documented IDIB formats can support IDIB. 
As with other interfaces, the IDIB must be Released when the user finishes with it. 


On failure, *p should be set to NULL, but it is good form to explicitly set *p to NULL 
before calling IBITMAP Querylnterface(). 


See Also: 
None 
Return to the List of functions 
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IBITMAP Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IBITMAP AddRef() 
Return to the List of functions. 
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IBITMAP RGBToNative() 


Description: 


This function converts an RGBVAL value into a native color value (pixel value). Native 
color values are the values stored in the pixel array; the mapping between native and 
RGB values is a property of the bitmap. If no NativeColor corresponds exactly to the 
specified RGBVAL, a close match is returned. This function is not required to return the 
closest match, and for performance reasons a close match (but not the closest) may 
be returned. 


Prototype: 


NativeColor IBITMAP RGBToNative (IBitmap *pIBitmap, RGBVAL RGBColor) 


Parameters: 


pIBitmap [in] Pointer to the IBitmap Interface. 
RGBColor [in] RGB value to be converted from. Only true RGB values are 
supported. Color table indices are not supported. 


Return Value: 
The corresponding native color value. 


Comments: 
If the bitmaps lack palette information, the result is undefined. 


See Also: 
RGBVAL 
IBITMAP NativeToRGB() 
Return to the List of functions 


140 


Breu IBitmap Interface 


IBITMAP SetPixels() 


Description: 
This function draws multiple pixels with the same color. 


Prototype: 
int IBITMAP SetPixels 
( 
IBitmap *pIBitmap, 
unsigned cent, 
AEEPoint *pPoint, 
NativeColor color, 
AEERaster0Op rop 
) 




















Parameters: 

pIBitmap [in] Pointer to the IBitmap Interface object to which the pixels are 
drawn. 

ent [in] Number of pixels. 

pPoint [in] Array of 2D points. 

color [in] Specifies the color to be used to draw the pixels. This is a native 
color, which is obtained using IBITMAP RGBToNative(). 

rop [in] Specifies the raster operation that is used to draw the pixel. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 
EBADPARM, if raster operation is invalid. 
Other implementation-specific error codes 


Comments: 
Only AEE RO COPY and AEE RO XOR are valid raster operations. 


Any other value passed as a parameter is treated lke AEE RO COPY. In the current 
version, this function returns EBADPARM. 


See Also: 
AEERasterOp 
IBITMAP GetPixel() 
Return to the List of functions 
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IBITMAP SetTransparencyColor() 


Description: 
This function sets the transparency color of the bitmap. This is used when this bitmap 
is the source bitmap of a transparent bit blit operation. For pixels that contain this 
NativeColor, the corresponding destination pixel is unaffected. 


Prototype: 

int IBITMAP SetTranparencyColor (IBITMAP *pMe, NativeColor color); 
Parameters: 

pMe [in] Pointer to the current bitmap interface. 

color [in] Color to make transparent. 


Return Value: 
SUCCESS, if the function executed correctly. 
Error code, if otherwise. 
Or other implementation-specific error codes 


Comments: 
None 


See Also: 
NativeColor 
IBITMAP BltIn() 
IBITMAP BKOut() 
IBITMAP GetTransparencyColor() 
Return to the List of functions 
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The IBitmapCil interface is used to enable and restrict access to the device bitmap. Itis used 
internally by BREW and is not available to applications. 


The purpose is to allow BREW to control which application is allowed to write to the screen. 
IBitmapCtl is an extension to the IBitmap interface, and is obtained through 
IBITMAP Querylnterface() with a class ID of AEECLSID BITMAPCTL. 


Itis a requirement of the OEM that this interface be implemented for the device bitmap. This 
interface does not need to be implemented for any other bitmaps. 


List of Header files to be included 

The following header file is required: 
OEMDisp.h 

List of functions 


Functions in this interface include: 


IBITMAPCTL AddRef() 
IBITMAPCTL Enable() 
IBITMAPCTL NotifyRelease() 
IBITMAPCTL Querylnterface() 
IBITMAPCTL Release() 
IBITMAPCTL Restrict() 


The remainder of this section provides details for each function. 
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IBITMAPCTL AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IBITMAPCTL Release() 
Return to the List of functions 
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IBITMAPCTL Enable() 


Description: 
This function is used to enable or disable drawing operations to the entire bitmap. 





Prototype: 

int IBITMAPCTL Enable (IBitmapCtl *pIBitmapCt1l, boolean bOn); 
Parameters: 

pIBitmapCtl [in] Pointer to the IBitmapCtl interface. 

bOn [in] TRUE if drawing will be allowed, otherwise FALSE. 


Return Value: 
SUCCESS, or error code. 


Comments: 
None. 


See Also: 
IBITMAPCTL Restrict() 
Return to the List of functions 
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IBITMAPCTL NotifyRelease() 














Description: 
This function is used to register for notification of release of the last reference to this 
bitmap. 
Prototype: 
int IBITMAPCTL NotifyRelease(IBitmapCtl *po, AEECallback *pchb); 
Parameters: 
po Pointer to IBitmapCtl interface. 
pcb Pointer to callback stucture. This callback will be triggered when the 


last reference to this bitmap is released. 


Return Value: 
SUCCESS is returned if function executed correctly. 
EBADPARM if pcb is NULL. 
Other values may be returned if other errors occur. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IBITMAPCTL Querylnterface() 


Description: 
This function is inherited from IQI Querylnterface(). 


See Also: 
Return to the List of functions 
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IBITMAPCTL Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IBITMAPCTL AddRef() 
Return to the List of functions 
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IBITMAPCTL Restrict() 


Description: 
This function restricts drawing operations to a portion of the bitmap. 














Prototype: 

int IBITMAPCTL Restrict (IBitmapCtl *pIBitmapCtl, AEERect *prc); 
Parameters: 

pIBitmapCtl [in] Pointer to IBitmapCtl interface. 

pre [in] Pointer to rectangle that that specifies where drawing is allowed. 


Return Value: 
SUCCESS is returned if function executed correctly. 
EBADPARM if pre is NULL. 
EUNSUPPORTED if function is not implemented. 


Comments: 
None. 


See Also: 
IBITMAPCTL Enable() 
Return to the List of functions 
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Description: 


The ICallHistory interface provides applications with the ability to add an entry to the 
Call History list, remove the entries, enumerate the entries in the list as well as get the 
number of entries in the list and the maximum list size. 


Predefined Field Types: 


An entry into the CallHistory is made up of one or more fields. Each field is composed 
of a ClassiD and FieldID which together indicate the type of data contained by the field. 
BREW has several pre-defined field types that represent information commonly 
associated with voice calls. For all of the predefined fields, the Clsld parameter should 
be set to O. User applications should not attempt to overload the predefined field types, 
but rather make an extended type assocaited with their own ClassID and possibly 
approximate the value with the predefined equivalent), so that applications that are not 
aware of the extended data type can continue to operate correctly. 


Predefined Fields: 

AEECALLHISTORY FIELD CALL TYPE (uint16): 

The call type must be one of the following values: 
AEECALLHISTORY CALL TYPE TO 
AEECALLHISTORY CALL TYPE FROM 
AEECALLHISTORY CALL TYPE MISSED 

AEECALLHISTORY FIELD NUMBER TYPE (uint16): 

The number type must be one of the following values: 
AEECALLHISTORY NUMBER TYPE INTERNATIONAL 
AEECALLHISTORY NUMBER TYPE NATIONAL 
AEECALLHISTORY NUMBER TYPE NETWORK 
AEECALLHISTORY NUMBER TYPE SUBSCRIBER 
AEECALLHISTORY NUMBER TYPE ABREVIATED 
AEECALLHISTORY NUMBER TYPE QCHAT 

AEECALLHISTORY FIELD NUMBER PLAN (uint16): 

The number plan must be one of the following values: 
AEECALLHISTORY NUMBER PLAN TELEPHONY 
AEECALLHISTORY NUMBER PLAN DATA 
AEECALLHISTORY NUMBER PLAN TELEX 
AEECALLHISTORY NUMBER PLAN PRIVATE 

AEECALLHISTORY FIELD DATE TIME (uint32): 
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The date and time of the origination of the phone call expressed as the number of 
seconds since Jan 6, 1980 00:00:00 GMT. This is the same format as the 
GETTIMESECONDS() helper function. 


AEECALLHISTORY FIELD CALL DURATION (uint32): 
The duration of the call, in seconds 
AEECALLHISTORY FIELD NUMBER (ASCII unterminated string): 


This is the number dialed. Valid characters for the string include the ASCII digits '0' - 
'9, FE, '“, and ';. The comma represents and OEM-defined soft pause. OEMs are free 
to truncate the number field as needed by their implementations. 


AEECALLHISTORY FIELD NAME (Unicode unterminated string): 


This is the text description of the call history entry. For custom call types like entries 
without a AEECALLHISTORY. FIELD NUMBER, this value will be displayed to 
describe the call. 


NOTE: OEMs may require certain pre-defined fields in an entry before that entry can 
be added or updated to the Call History. Check OEM documentation to determine 
which, if any, fields are required. 


NOTE: OEMs may not store all field types. If an entry to be added/updated contains 
field types that the OEM cannot store, the function will return SUCCESS, and only 
those fields that are supported by the OEM will be available to be retrieved via the 
enumeration functions. . 


List of Header files to be included 


The following header file is required: 


AEECallHistory.h 


List of functions 


Functions in this interface include: 


ICALLHISTORY. Clear() 
ICALLHISTORY. AddEntry() 
ICALLHISTORY. Enuminit() 
ICALLHISTORY. EnumNext() 
ICALLHISTORY. UpdateEntry() 


The remainder of this section provides details for each function. 


191 


Erei ICallHistory Interface 


ICALLHISTORY Clear() 


Description: 
This deletes all entries from the Call History list in the current storage. 


Prototype: 

int ICALLHISTORY Clear (ICallHistory *pich) 
Parameters: 

pich Pointer to an ICallHistory interface object 


Return Value: 
SUCCESS if successful 
EFAILED or other applicable BREW error if failed to delete entries 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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ICALLHISTORY AddEntry() 


Description: 
This function adds a new entry to the Call History list in the current set storage. If the 
maximum number of entries is reached, the will delete the oldest entry in the list, and 
add the new entry at the top of the list. 


Prototype: 


int ICALLHISTORY AddEntry 
( 
ICallHistory *pich, 
const AEECallHistoryEntry *pche 
); 




















Parameters: 
pich Pointer to an ICallHistory interface object 
pche new entry 


Return Value: 
SUCCESS if successful 


EBADPARM if field data is not valid for field type or invalid AEECallHistory entry 
structure. 


EFAILED or other applicable BREW error if failed to delete entries 


Comments: 
The memory specified in pche is copied by the ICALLHISTORY implementation, and 
need not be maintained by the caller after the call to AddEntry() 


See Also: 
AEECallHistoryEntry 
Return to the List of functions 
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ICALLHISTORY. Enuminit() 


Description: 
This initializes/resets the enumeration in the Call History list. 





Prototype: 

int ICALLHISTORY EnumInit (ICallHistory *pich) 
Parameters: 

pich Pointer to an ICallHistory interface object 


Return Value: 
SUCCESS if successful 
EFAILED or another BREW error if an error occurs (ENOMEMORY, etc.) 


Comments: 
None 


See Also: 
ICALLHISTORY. EnumNext() 
Return to the List of functions 
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ICALLHISTORY. EnumNext() 


Description: 


ICallHistory Interface 


This retrieves the next entry in the Call History list ftom current storage. 
ICALLHISTORY Enuminit() must be called before any successive calls to this 
function. Call History entries are returned in reverse chronilogical order of addition to 
the system (i.e. Newest record first ). 














Prototype: 
const AEECall 
( 
T 
int *pnl 
) 
Parameters: 
pich [ 
pnErr [ 


Return Value 





History! 


Err 


in] 
out] 


Entry ICALLHISTORY.. 


CallHistory *pche, 





EnumNext 


Pointer to an ICallHistory interface object 


Pointer to an integer to hold any error value, set to 
SUCCESS if successful or at end of enumeration EFAILED 
or another BREW error if an error occurs 


The "next" callhistory entry, if applicable 


NULL if we're at the last entry or an error occurs 


Comments: 


The memory pointed to by the returned AEECallHistory Entry is owned by the 
ICALLHISTORY object. Its contents will stay valid until the next call to 
ICALLHISTORY EnumNext(), ICALLHISTORY Enumtinit(), or 

ICALLHISTORY Release(). The contents of the returned pointer must not be modified 
by the caller. 


See Also: 


AEECallHistoryEntry 
Return to the List of functions 
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ICALLHISTORY. UpdateEntry() 


Description: 
This replaces the current call history entry with the one provided. The current entry is 


defined as the entry that was returned during the most recent call to 
ICALLHISTORY. EnumNext(). 


Prototype: 


int ICALLHISTORY UpdateEntry 
( 
ICallHistory *pich, 
const AEECallHistoryEntry *pche 
); 




















Parameters: 
pich Pointer to an ICallHistory interface object 
pche New data to replace existing entry 


Return Value: 
SUCCESS if successful 
EFAILED or some other BREW error if failed to update entries 


EBADPARM if field data is not valid for field type or invalid AEECallHistory entry 
structure. 


Comments: 
None 


See Also: 
AEECallHistoryEntry 
Return to the List of functions 
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ICamera interface provides a generic way to BREW applications to control device camera and 
to record snapshots and movies in various formats like JPEG, MPEG4, and others. 


Event Notification: 


ICamera asynchronously notifies all the events to client app via the callback function. 
App must register a callback notification function using ICAMERA RegisterNotify(). 


Display: 
ICamera dispatches the captured frames via user registered callback function in 
preview, snapshot and movie modes. The frame is deliverd via 
CAM STATUS FRAME callback. In the callback, user needs to call 
ICAMERA GetFrame() to get the frame represented by IBitmap. 


tis app's responsibility to display these frames on to the screen or other destination. 
ICamera DOES NOT perform any display operations. 


Preview Mode: 


Before you start camera in preview mode, you need to perform the following 
operations: 


(1) ICAMERA SetDisplaySize() to set the frame display size 
(2) [Optional] IIAMERA SetFramesPerSecond() to set the FPS of the camera 


ICAMERA Preview() starts the camera in preview mode. CAM STATUS START 
callback will be sent to app. Preview frames are delivered via CAM STATUS FRAME 
callback. Use ICAMERA GetFrame() to retrieve the frame. 


ICAMERA Pause() stops the frame callbacks. ICAMERA Resume() resumes the 
frame callbacks. 


ICAMERA Stop() stops the preview operation and puts the camera in ready mode. 
CAM STATUS DONE callback will be sent to app. 


Snapshot Mode: 
Before you do snapshot operation, you need to perform the following operations: 
(1) ICAMERA SetMediaData() 
2) ICAMERA SetSize() 
3) [Optional] ICAMERA SetVideoEncode() 
4) [Optional] IIAMERA SetQuality() 
5) [Optional] ICAMERA SetFramesPerSecond() 


mm pm pm 
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ICAMERA RecordSnapshot() starts the snapshot recording operation. 

CAM STATUS START callback will be sent to app followed by CAM STATUS DONE 
when recording is complete. When the encoding is completed, 

(CAM CMD ENCODESNAPSHOT, CAM STATUS DONE) callback will be sent. 


ICamera can be configured to defer the snapshot encoding as follows. This is known 
as DeferEncode feature. Note that, by default, DeferEncode is disabled. 


(1) ICAMERA SetMediaData() 


(2)ICAMERA DeferEncode(). Use ICAMERA DeferEncode(TRUE) to Indicate 
that encoding must be defered 


ICAMERA EncodeSnapshot() starts the snapshot recording operation. 

CAM STATUS START callback will be sent to app followed by CAM STATUS DONE 
when recording is complete. Now, only raw frame is recorded and itis not yet encoded. 
App can access the raw frame using ICAMERA GetFrame() in the callback. 
ICAMERA EncodeSnapshot() encodes the frame and sends 

(CAM CMD ENCODESNAPSHOT, CAM STATUS DONE) callback when encoding 
is done. Do ICAMERA SetMediaData() before calling ICAMERA EncodeSnapshot(). 


Movie Mode: 


Before you do start recording movie, you need to perform the following operations: 
(1) ICAMERA SetMediaData() 
(2) ICAMERA SetSize() 
(3) [Optional] ICAMERA SetVideoEncode() and ICAMERA SetAudioEncode() 
(4) [Optional] ICAMERA SetQuality() 
(5) [Optional] ICAMERA SetFramesPerSecond() 

Recorded frames are delivered via CAM STATUS FRAME callback. Use: 
ICAMERA GetFrame() to retrieve the frame. 
ICAMERA Pause() pauses recording as well as stops the frame callbacks. 
ICAMERA Resume() resumes the recording and the frame callbacks. 


ICAMERA Stop() stops the record operation and puts the camera in ready mode. 
CAM STATUS DONE callback will be sent to app. 


App Suspend/Resume: 


When app gets EVT APP SUSPEND, itis recommended that app stop the camera 
and release ICamera interface. 


When app gets EVT APP RESUME, it can create ICamera interface and resume its 
operation. 
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Sample Code: 


The following code snippet starts the camera in preview mode and displays frames to 
the device screen. 


static int CApp StartCameraInPreviewMode (CApp * pme) 
t 





int nErr; 
// Create ICamera instance. 
nErr = ISHELL CreateInstance (pme->a.m pIShell, AEECLSID CAMI 
(void **) spme->m pICamera); 
if (nErr) 








T 











EM 





RA, 





return nErr; 
// Register callback notification function. 
nRet = ICAMERA RegisterNotify (pme->m pICamera, 
CApp CameraNotify, pme); 
if (nErr) 





return nErr; 
ICAMERA SetDisplaySize (pme->m pICamera, &pme->m sizePreview); 
nErr = ICAMERA Preview (pme->m pICamera) ; 
if (nErr) 











return nErr; 
return SUCCESS; 





) 
static void CApp CameraNotify (void * pUser, AEECameraNotify * pn) 
t 














CApp * pme = (CApp *)pUser; 
1f (!pme || !pn) 
return; 


switch (pn->nStatus) 
f 
case CAM STATUS START: 
// Preview has begun... 
break; 
case CAM STATUS FRAME: 
t 
IBitmap * pFrame; 
AEEBitmapInfo bi; 

















// 
// IMPORTANT NOTE: You need to do IBITMAP Release (pFrame) after 
you're done with pFrame. 











/( 
if (SUCCESS == ICAMERA GetFrame (pme->m pICamera, &pFrame)) 
return; 


// Get the bitmap info...this can be saved in app global structure. 
IBITMAP GetInfo (pFrame, «bi, sizeof(bi)); 


// Display the frame at (0, 0) location of the screen 
IDISPLAY BitBlt (pme, 0, O, bi.cx, bi.cy, pFrame, 0, O, 
AEE RO COPY); 
IBITMAP Release (pFrame) ; 
break; 
) 
case CAM STATUS DONE: 








T 











Em 
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// ICAMERA Stop() was called and preview operation stopped. 
break; 
case CAM STATUS ABORT: 
// Preview got aborted. 
break; 
) 
) 





Camera State Machine: 











Preview() RecordSnapshot() RecordMovie() 









Stop() Stop() 

DONE/ DONE/ DONE/ 

ABORT ABORT ABORT 
PREVIEW SNAPSHOT 


Pause() Pause() 
Resume() Resume() 
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ICamera Call Flow for Preview Mode 


BREW App 
[ICamera BREW ICamera Example OEM Camera Layer 
State] 
ICAMERA SetDisplaySize() > 
[READY] ICAMERA Preview() > 
camera start preview() > 
[PREVIEW] < SUCCESS 


< CAM CMD START/CAM STATUS START 
< FRAME 


< CAM CMD START/CAM STATUS FRAME 


ICAMERA GetFrame() > 
[returns PreviewFrame IBitmap] > 
< FRAME 
< CAM CMD START/CAM STATUS FRAME 


ICAMERA GetFrame() > 


[returns PreviewFrame IBitmap] > 
ICAMERA Stop() > 


camera stop preview() > 


[READY] < DONE 
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ICamera Call Flow for Picture Taking Mode 


Record SnapShot (Immediate Encoding) 


BREW App 
[ICamera BREW ICamera Example OEM Camera Layer 
State] 

ICAMERA SetMediaData() > 

ICAMERA SetVideoEncode() > 

ICAMERA SetSize() > 

[Optional|ICAMERA SetQuality() > 

[READY] ICAMERA RecordSnapshot() > 


camera take picture() > 
< SUCCESS 
[SNAPSHOT] < CAM STATUS START 
< DONE(SnapshotFrame) 


[READY] — <CAM CMD START/ 
CAM STATUS DONE 


camera encode(SnapshotFrame) > 
< SUCCESS 
< DONE 


[READY] < CAM CMD ENCODESNAPSHOT/ 
CAM STATUS DONE 
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ICamera Call Flow for Recording SnapShot (deferred encoding) Mode 


BREW App 
[ICamera BREW ICamera Example OEM Camera Layer 
State] 

ICAMERA DeferEncode() > 

ICAMERA SetMediaData() > 

ICAMERA SetVideoEncode() > 

ICAMERA SetSize() > 

ICAMERA SetQuality() > 

[READY] ICAMERA RecordSnapshot() > 


camera take picture() > 
< SUCCESS 
[ISNAPSHOT] < CAM STATUS START 
< DONE(SnapshotFrame) 
[READY] < CAM CMD START/CAM STATUS DONE 
ICAMERA GetFrame() > 
[returns SnapshotFrame IBitmap] > 
ICAMERA EncodeSnapshot(SnapshotFrame) > 
camera encode(SnapshotFrame) > 
< SUCCESS 
< DONE 


[READY] < CAM CMD ENCCODESNAPSHOT/ 
CAM STATUS DONE 


ICamera Call Flow for Recording Movie Mode 


BREW App 
[ICamera BREW ICamera Example OEM Camera Layer 
State] 

ICAMERA SetMediaData() > 

ICAMERA SetVideoEncode() > 

ICAMERA SetAudioEncode() > 

ICAMERA SetSize() > 

[Optional]ICAMERA SetQuality() > 

[OptionalllCAMERA SetFramesPerSecond() > 

[READY] ICAMERA RecordMovie() > 
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[MOVIE] 


[READY] 


ICamera Interface 


camera start record() > 
< SUCCESS 
< CAM CMD START/CAM STATUS START 
< FRAME 
< CAM CMD START/CAM STATUS FRAME 
ICAMERA GetFrame() > 
[returns MovieFrame IBitmap] > 
< FRAME 
< CAM CMD START/CAM STATUS FRAME 
ICAMERA GetFrame() > 


[returns MovieFrame IBitmap] > 


ICAMERA Pause() > 
camera pause record() > 
< SUCCESS 
< CAM CMD START/CAM STATUS PAUSE 
ICAMERA Resume() > 
camera resume record() > 
< SUCCESS 
< CAM CMD START/CAM STATUS RESUME 


ICAMERA Stop() > 
camera stop record() > 
< DONE 
< CAM CMD START/CAM STATUS DONE 


List of Header files to be included 


The following header file is required: 


AEECamera.h 
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List of functions 


Functions in this interface include: 


ICAMERA AddOverlay() 
ICAMERA AddRef() 
ICAMERA ClearOverlay() 
ICAMERA DeferEÊncode() 
ICAMERA EncodeSnapshot() 
ICAMERA GetDisplaySizeList() 
ICAMERA GetFrame() 
ICAMERA GetMode() 
ICAMERA GetParm() 
ICAMERA GetSizeList() 
ICAMERA IsBrightness() 
ICAMERA IsContrast() 
ICAMERA IsMovie() 
ICAMERA IsSharpness() 
ICAMERA IsSupport() 
ICAMERA IsZoom() 
ICAMERA Pause() 

ICAMERA Preview() 
ICAMERA Querylnterface() 
ICAMERA RecordMovie() 
ICAMERA RecordSnapshot() 
ICAMERA RegisterNotify() 
ICAMERA Release() 
ICAMERA Resume() 
ICAMERA RotateEncode() 
ICAMERA RotatePreview() 
ICAMERA SetAudioEncode() 
ICAMERA SetBrightness() 
ICAMERA SetContrast() 
ICAMERA SetDisplaySize() 
ICAMERA SetFramesPerSecond() 
ICAMERA SetMediaData() 
ICAMERA SetParm() 
ICAMERA SetQuality() 
ICAMERA SetSharpness() 
ICAMERA SetSize() 
ICAMERA SetVideoEncode() 
ICAMERA SetZoom() 
ICAMERA Start() 

ICAMERA Stop() 


The remainder of this section provides details for each function. 
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ICAMERA AddOverlay() 


Description: 


This function sets the overlay image that will be part of the recorded picture. This 
operation is done any camera mode. 


Prototype: 


int ICAMERA AddOverlay 
( 
ICamera * pICamera, 
IBitmap * pb 
) 





Parameters: 
piCamera Pointer to ICamera Interface. 
pb Pointer to IBitmap representing the overlay 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


You can add overlays on top of another image by calling this function repeatedly with 
different images. To clear ALL overlays, call ICAMERA ClearOverlay(). 


See Also: 


ICAMERA SetParm() 
ICAMERA ClearOverlay() 
Return to the List of functions 
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ICAMERA AddRef() 


Description: 
This function increments the reference count of the ICamera Interface object. This 
allows the object to be shared by multiple callers. The object is freed when the 
reference count reaches O (zero). 


Prototype: 


uint32 ICAMERA AddRef (ICamera * pICamera) 





Parameters: 
piCamera: Pointer to the ICamera Interface object 


Return Value: 
Incremented reference count for the object 


Comments: 
A valid object returns a positive reference count. 


See Also: 
ICAMERA Release() 
Return to the List of functions 
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ICAMERA ClearOverlay() 


Description: 
This function clears all the overlaid images. 





Prototype: 

int ICAMERA ClearOverlay (ICamera * pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA GetParm() 
ICAMERA ClearOverlay() 
Return to the List of functions 
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ICAMERA DeferEncode() 


Description: 


This function defers the encoding of the snapshot done by 
ICAMERA RecordSnapshot() API. You need to explicitly call 
ICAMERA EncodeSnapshot() to encode the snapshot. 


Prototype: 


int ICAMERA DeferEncode 
( 
ICamera * pICamera, 
boolean bDefer 


) 








Parameters: 
piCamera Pointer to ICamera Interface. 
bDefer TRUE implies the encoding will be done by user. 


Return Value: 
SUCCESS if successful. 
Error code if failure. 


Comments: 
None 


See Also: 
ICAMERA Start() 
ICAMERA RecordSnapshot() 
ICAMERA EncodeSnapshot() 
Return to the List of functions 
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ICAMERA EncodeSnapshot() 


Description: 
This function, typically, encodes the recorded snapshot. 


Prototype: 


int ICAMERA EncodeSnapshot 
( 
ICamera * pICamera, 


) 














Parameters: 


piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS if successful. 
Error code if failure. 


Comments: 


This API is typically called in response to CAM STATUS DONE when 
ICAMERA RecordSnapshot(). You can use ICAMERA GetFrame()() to get the latest 
raw snapshot frame. 


This function results in (CAM CMD ENCODESNAPSHOT, CAM STATUS DONE) 
callback after the snapshot is encoded. 


This API can be called in any mode. It may abort the current active operation like 
preview, movie, encode snapshot, etc. It may also be used to encode any frame, if 
supported. 


See Also: 
ICAMERA Start() 
ICAMERA RecordSnapshot() 
ICAMERA GetFrame() 
Return to the List of functions 
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ICAMERA GetDisplaySizeList() 


Description: 


This function retrieves the list of discrete display sizes supported for specified mode or 
continuous range (e.g. any size between 10x10 to 100x150). 


Prototype: 

int ICAMERA GetDisplaySizeList 
( 
ICamera * pICamera, 
AEESize ** ppList, 
boolean * pbRange 
) 














Parameters: 
piCamera [in] Pointer to ICamera Interface. 
ppList [in] *ppList contains 
CAM MODE PREVIEW/CAM MODE MOVIE 
[out] Pointer to NULL- terminated size list 
pbRange [out] Pointer to boolean when TRUE indicates the passed list is a 


NULL-terminated paired list (i.e. multiple of 2) of ranges 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
The list should be copied and should not be freed. 


See Also: 
ICAMERA GetParm() 
AEESize 
Return to the List of functions 
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ICAMERA GetFrame() 


Description: 
This function returns the current frame captured by the camera. 





Prototype: 

IBitmap * ICAMERA GetFrame (ICamera * pICamera, IBitmap ** ppFrame) ; 
Parameters: 

piCamera [in] Pointer to ICamera Interface. 

ppFrame [out] Frame IBitmap returned . 


Return Value: 
SUCCESS, if successful 
Error code, if failure. 


Comments: 


This function is typically called in response to CAM STATUS FRAME callback. Itis 
caller's responsibility to release the IBitmap object after calling this function. 


The caller can Query Interface, on the returned IBitmap, for IDIB which, if supported, 
allows access to frame data. 


See Also: 
ICAMERA Start() 
ICAMERA Preview() 
ICAMERA RecordMovie() 
Return to the List of functions 
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ICAMERA GetMode() 


Description: 
This function returns the current camera mode. 


Prototype: 


int ICAMERA GetMode 
( 
ICamera * pICamera, 
int1l6 * pnMode, 
boolean * phbPaused 


) 





Parameters: 
piCamera [in] Pointer to ICamera Interface. 
pnMode [out] Pointer to mode. CAM MODE XXX 
pbPaused [out] TRUE/FALSE 


Paused/Resumed 


Return Value: 
SUCCESS: Successful. Operation completed. 
EBADPARM: Bad parm 


Comments: 
None 


See Also: 
ICAMERA Start() 
Return to the List of functions 
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ICAMERA GetParm() 


Description: 
This function gets the camera control parameters. 


Prototype: 


int ICAMERA GetParm 
( 
ICamera * pICamera, 
int16 nParmID, 
int32 * pP1, 
int32: * pPRZ 
) 





Parameters: 
piCamera Pointer to ICamera Interface. 
nParmiD CAM PARM XXX 
pP1 Depends on the nParmlD parameter 
pP2 Depends on the nParmlD parameter 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
See Camera Control Parameters for parameter details. 


See Also: 
ICAMERA SetParm() 
Camera Control Parameters 
Return to the List of functions 
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ICAMERA GetSizeList() 


Description: 


This function retrieves the list of discrete sizes supported for specified mode or 
continuos range (e.g. any size between 10x10 to 100x150). 


Prototype: 


int ICAMERA GetSizeList 
( 
ICamera * pICamera, 
AEESize ** ppList, 
boolean * pbRange 

) 

















Parameters: 
piCamera [in] Pointer to ICamera Interface. 
ppList [in] ppList contains 
CAM MODE SNAPSHOT/CAM MODE MOVIE 
[out] Pointer to NULL- terminated size list 
pbRange [out] Pointer to boolean when TRUE indicates the passed list is a 


NULL-terminated paired list (i.e. multiple of 2) of ranges 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
The list should be copied and should not be freed. 


See Also: 


ICAMERA GetParm() 
AEESize 


Return to the List of functions 
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ICAMERA IsBrightness() 


Description: 
This function checks if camera has brightness setting capability. 


Prototype: 


int ICAMERA IsBrightness 
( 
ICamera * pICamera, 
boolean * pbSupport 
) 





Parameters: 
plICamera [in] Pointer to ICamera Interface. 
pbSupport [out] Pointer to boolean. TRUE/FALSE => 


Supported/Unsupported. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA IsSupport() 
Return to the List of functions 
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ICAMERA IsContrast() 


Description: 
This function checks if camera has contrast setting capability. 


Prototype: 


int ICAMERA IsContrast 
( 
ICamera * pICamera, 
boolean * pbSupport 
) 





Parameters: 
plCamera [in] Pointer to ICamera Interface. 
pbSupport [out] Pointer to boolean. TRUE/FALSE => 


Supported/Unsupported. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA IsSupport() 
Return to the List of functions 
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ICAMERA IsMovie() 


Description: 
This function checks if camera has movie recording capability. 


Prototype: 


int ICAMERA IsMovie 
( 
ICamera * pICamera, 
boolean * pbSupport 
) 





Parameters: 
piCamera [in] Pointer to ICamera Interface. 
pbSupport [out] Pointer to boolean. 


TRUE/FALSE => Supported/Unsupported. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA IsSharpness() 


Description: 
This function checks if camera has sharpness setting capability. 


Prototype: 


int ICAMERA IsSharpness 
( 
ICamera * pICamera, 
boolean * pbSupport 
) 





Parameters: 
plICamera [in] Pointer to ICamera Interface. 
pbSupport [out] Pointer to boolean. TRUE/FALSE => 


Supported/Unsupported. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA IsSupport() 
Return to the List of functions 
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ICAMERA IsSupport() 


Description: 


This function checks if specified parameter is supported by ICamera Interface. This 
function is useful to check the camera capabilities like setting of brightness, zoom, etc. 


Prototype: 


int ICAMERA IsSupport 
( 
ICamera * pICamera, 
int16 nParmID, 
boolean * pbSupport 
) 





Parameters: 
plCamera [in] Pointer to ICamera Interface. 
nParmiD [in] CAM PARM XXX parameter ID.See Camera Control 
Parameters 
pbSupport [out] Pointer to boolean. TRUE/FALSE => 
Supported/Unsupported. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 


180 


Eri ICamera Interface 


ICAMERA IsZoom() 


Description: 
This function checks if camera has zoom capability. 


Prototype: 


int ICAMERA IsZoom 
( 
ICamera * pICamera, 
boolean * pbSupport 
) 





Parameters: 
plICamera [in] Pointer to ICamera Interface. 
pbSupport [out] Pointer to boolean. TRUE/FALSE => 


Supported/Unsupported. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Value retumed via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot get parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA IsSupport() 
Return to the List of functions 
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ICAMERA Pause() 


Description: 


This function pauses the camera operation. In preview and record modes, the frame 
callbacks are paused. In record mode, the encoding is also paused. 





Prototype: 

int ICAMERA Pause (ICamera * pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
ENOMEMORY: Not enough memory 
EBADSTATE: Pause cannot be done in current state 


Comments: 
This API does not apply to Snapshot mode. 
This function results in CAM STATUS PAUSE status callback. 
In the callback, AEECameraNotify, 
nCmd = CAM CMD START and nSubCmd = CAM MODE PREVIEW/CAM MODE MOVIE. 





























See Also: 


ICAMERA Start() 
ICAMERA Preview() 
ICAMERA RecordMovie() 
ICAMERA Resume() 


Return to the List of functions 
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ICAMERA Preview() 


Description: 


This function starts the camera operation in preview mode, which causes ICamera to 
start sending frames to the client. 





Prototype: 

int ICAMERA Preview (ICamera * pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
EBADPARM: Bad parm is passed 
ENOMEMORY: Not enough memory 
EBADSTATE: Preview cannot be done in current state 


Comments: 


You need to set the frame display size before calling this function. All the events that 
originate due to this API and due to the following APIs will be reported via the user- 
specified callback: 


ICAMERA Stop() 
ICAMERA Pause() 
ICAMERA Resume() 
CAM STATUS START callback happens once the preview begins. 
CAM STATUS FRAME callbacks happen continuously unless you pause. 
CAM STATUS DONE callback occurs when preview is stopped. 
CAM STATUS ABORT callback occurs when preview is aborted. 
In the callback, AEECameraNotify, 
nCmd = CAM CMD START and nSubCmd = CAM MODE PREVIEW. 

















See Also: 


ICAMERA Start() 
ICAMERA Stop() 
ICAMERA Pause() 
ICAMERA Resume() 
ICAMERA GetFrame() 


Return to the List of functions 
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ICAMERA Querylnterface() 


Description: 
This function can be used to 
* Get a pointer to an interface or data based on the input class ID 
* Query an extended version of the ICamera-derived class 
* Support version compatibility 


Prototype: 

int ICAMERA QueryInterface 
( 
ICamera * pICamera, 
ABECLSID clsReg, 
void ** ppo 


) 














Parameters: 
plCamera [in] Pointer to ICamera Interface. 
clsReq [in] A globally unique id to identify the entity (interface or 
data) that we are trying to query. 
ppo [out] Pointer to the interface or data that we want to retrieve. 


If the value passed back is NULL, the interface or data 
that we query are not available. 


Return Value: 
Return SUCCESS on success, otherwise returns error code. 


Comments: 
If ppo is back a NULL pointer, the interface or data that we query is not available. 


Side Effects: 


If an interface is retrieved, then this function increments its reference count. 
If a data structure is retrieved, then a pointer to the internal structure is given and user 
should not free it. 


See Also: 
None 
Return to the List of functions 
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ICAMERA RecordMovie() 


Description: 


This function starts the camera operation in movie mode, which causes recorded 
frames to be sent to the caller while encoding those frames. 





Prototype: 

int ICAMERA RecordMovie (ICamera * pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
EBADPARM: Bad parm is passed 
ENOMEMORY: Not enough memory 
EBADSTATE: RecordMovie() cannot be done in current state 


Comments: 


You need to set the media data before calling this function. Also, you may want to 
specify active encoding, picture format and quality that should be used for encoding 
the movie. 


All the events that originate due to this API and due to the following APIs will be 
reported via the user-specified callback: 


ICAMERA Stop() 

ICAMERA Pause() 

ICAMERA Resume() 
CAM STATUS START callback happens once the recording begins. 
CAM STATUS FRAME callbacks happen continuously unless you pause. 
CAM STATUS DONE callback occurs when recording is stopped. 


CAM STATUS ABORT callback occurs when recording is aborted. In the 
callback, AEECameraNotify, 


nCmd = CAM CMD START and nSublmd = CAM MODE MOVIE. 














See Also: 
ICAMERA Start() 
ICAMERA Stop() 
ICAMERA Pause() 
ICAMERA Resume() 
ICAMERA GetFrame() 


Return to the List of functions 
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ICAMERA RecordSnapshot() 


Description: 


This function starts the camera operation in snapshot mode which causes the camera 
to take a snapshot. If Defer Encoding is not enabled (default), this function causes the 
snapshot to be encoded. 





Prototype: 

int ICAMERA RecordSnapshot (ICamera *pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
EBADPARM: Bad parm is passed 
ENOMEMORY: Not enough memory 
EBADSTATE: RecordSnapshot() cannot be done in current state 


Comments: 


You need to set the media data before calling this function. Also, you may want to 
specify active encoding, picture format and quality that should be used for encoding 
the snapshot. In the callback, AEECameraNotify, if nCmd = CAM CMD START, then 
nSubCmd = CAM MODE SNAPSHOT. 


This function results in (CAM CMD START, CAM STATUS START) callback 
followed by (CAM CMD START, CAM STATUS DONE) callback after the snapshot 
is taken. This is followed by (CAM CMD ENCODESNAPSHOT, 

CAM STATUS DONE) callback after the snapshot is encoded. 


You can defer encoding by calling ICAMERA DeferEncoding(plCamera, TRUE); This 
causes ICAMERA RecordSnaphot() not to encode the snapshot. You can get the raw 
snapshot frame using ICAMERA GetFrame() and call IIAMERA EncodeSnapshot() 
to encode the snapshot. 


See Also: 


ICAMERA Start() 

ICAMERA EncodeSnapshot() 
ICAMERA DeferEÊncode() 
ICAMERA GetFrame() 


Return to the List of functions 
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ICAMERA RegisterNotify() 


Description: 


This function registers a callback notification function with ICamera object. ICamera 
reports asynchronous events using this callback. 


Prototype: 
int ICAMERA RegisterNotify 
( 
IMedia * pICamera, 
PEFNCAMERANOTIFY pfnNotify, 
void * pUser 


) 








Parameters: 
piCamera Pointer to the IMedia Interface object 
pfnNotify User callback function pointer 
pUser User data to be used when calling pfnNotify() 


Return Value: 
SUCCESS: Successful. 
EBADSTATE: Error - IMedia is not in Ready state. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ICAMERA Release() 


Description: 
This function decrements the reference count of an object. The object is freed 
from memory and is no longer valid once the reference count reaches O (zero). 


Prototype: 


uint32 ICAMERA Release (ICamera * pICamera) 





Parameters: 
piCamera: Pointer to the ICamera Interface object 


Return Value: 
Decremented reference count for the object. The object has been freed and is no 
longer valid if O (zero) is returned. 


Comments: 
None 


See Also: 
ICAMERA AddRef() 
Return to the List of functions 
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ICAMERA Resume() 


Description: 


This function resumes the camera operation. In preview and record modes, the frame 
callbacks are resumed. In record mode, the encoding is also resumed. 





Prototype: 

int ICAMERA Resume (ICamera * pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
ENOMEMORY: Not enough memory 
EBADSTATE: Resume cannot be done in current state 


Comments: 


This API does not apply to Snapshot mode. This function results in 
CAM STATUS RESUME status callback. In the callback, AEECameraNotify, 


nCmd = CAM CMD START and nSubCmd = CAM MODE PREVIEW/CAM MODE MOVIE. 





























See Also: 
ICAMERA Start() 
ICAMERA Pause() 
ICAMERA Preview() 
ICAMERA RecordMovie() 
ICAMERA RecordSnapshot() 


Return to the List of functions 
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ICAMERA RotateEncode() 


Description: 


This function rotates the recorded and encoded frame. Only snapshot and movie 
modes are affected. 








Prototype: 

int ICAMERA RotateEncode (ICamera * pICamera, int32 nValue); 
Parameters: 

piCamera Pointer to ICamera Interface. 

nValue Rotation angle 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM ROTATE ENCODE details. 


See Also: 
ICAMERA GetParm() 
ICAMERA RotatePreview() 
Return to the List of functions 
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ICAMERA RotatePreview() 


Description: 
This function rotates the preview frame. Only preview mode is affected. 





Prototype: 

int ICAMERA RotatePreview(ICamera * pICamera, int32 nValue); 
Parameters: 

piCamera Pointer to ICamera Interface. 

nValue Rotation angle 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM ROTATE PREVIEW details. 


See Also: 
ICAMERA GetParm() 
ICAMERA RotateEncode() 
Return to the List of functions 
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ICAMERA SetAudioEncode() 


Description: 
This function sets the active audio encoding type used to encode along with the 
recorded snapshot/movie. 


Prototype: 

int ICAMERA SetAudioEncode 
( 
ICamera * pICamera, 
AEECLSID cls, 
uint32 dwExtra 


) 




















Parameters: 
piCamera Pointer to ICamera Interface. 
cls Encoding class ID. E.g. AEECLSID MEDIAQCP, etc. 
dwExtra Extra info regarding the encoding like sub formats. E.g. For 


AEECLSID MEDIAQCP, sub-format can be specified as 
MM QCP FORMAT FIXED FULL EVRC. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM AUDIO ENCODE details. 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 


192 


Eai ICamera Interface 


ICAMERA SetBrightness() 


Description: 
This function sets the brightness of the camera. 


Prototype: 


int ICAMERA SetBrightness 
( 
ICamera * pICamera, 
int32 nValue 


) 





Parameters: 
piCamera Pointer to ICamera Interface. 
nValue Brightness value. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM BRIGHTNESS details. 


See Also: 


ICAMERA GetParm() 
AEEParminio 


Return to the List of functions 
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ICAMERA SetContrast() 


Description: 
This function sets the contrast of the camera. 


Prototype: 


int ICAMERA SetContrast 
( 
ICamera * pICamera, 
int32 nValue 


) 





Parameters: 
piCamera Pointer to ICamera Interface. 
nValue Contrast value. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM CONTRAST details. 


See Also: 


ICAMERA GetParm() 
AEEParminito 


Return to the List of functions 
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ICAMERA SetDisplaySize() 


Description: 
This function sets the frame display size where the captured data is displayed. 


Prototype: 


int ICAMERA SetDisplaysSize 
( 
ICamera * pICamera, 
AFEESize * pSize 
) 














Parameters: 
piCamera Pointer to ICamera Interface. 
pSize Frame display size within the main display/off-srceen buffer area 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA SetFramesPerSecond() 


Description: 
This function sets the frames per second setting of camera in preview or movie mode. 


Prototype: 


int ICAMERA SetFramesPerSecond 
( 
ICamera * pICamera, 
uint32 dwFPS 
) 





Parameters: 


piCamera Pointer to ICamera Interface. 


dwFPS Frames per second. See dwFPS formatin CAM PARM FPS 
documentation. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM FPS details. 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA SetMediaData() 


Description: 
This function sets the media data where the recorded and encoded data will be saved. 


Prototype: 


int ICAMERA SetMediaData 
( 
ICamera * pICamera, 
AEEMediaData * pmd, 
const char * cpszMIME 


) 

















Parameters: 
piCamera Pointer to ICamera Interface. 
pmd Pointer to media data 


cpszMIME MIME type of the media 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
None 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA SetParm() 


Description: 
This function sets the camera control parameters. 


Prototype: 


int ICAMERA SetParm 
( 
ICamera * pICamera, 
int16 nParmID, 





int32 pl, 
1nt32: p2 
) 
Parameters: 
piCamera Pointer to ICamera Interface. 
nParmiD CAM PARM XXX. See Camera Control Parameters 
p1 Depends on the nParmlD parameter 
p2 Depends on the nParmlD parameter 


Return Value: 
SUCCESS: Successful. Operation is completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 
See Camera Control Parameters for parameter details. 


]JSee Also: 
ICAMERA GetParm() 
Camera Control Parameters 
Return to the List of functions 
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ICAMERA SetQuality() 


Description: 
This function sets the camera to capture specified picture quality. 


Prototype: 


int ICAMERA SetQuality 
( 
ICamera * pICamera, 
int1l6 nQuality 
) 





Parameters: 
piCamera Pointer to ICamera Interface. 
nQuality Picture quality 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM QUALITY details. 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA SetSharpness() 


Description: 
This function sets the sharpness of the camera. 


Prototype: 


int ICAMERA SetSharpness 
( 
ICamera * pICamera, 
int32 nValue 


) 





Parameters: 
piCamera Pointer to ICamera Interface. 
nValue Sharpness value. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM SHARPNESS details. 


ICAMERA GetParm() with CAM PARM SHARPNESS, returns AEEParminfo that 
specifies the sharpness info. 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA SetSize() 


Description: 
This function sets the camera to record a snapshot or movie in specified size. 


Prototype: 


int ICAMERA SetSize 
( 
ICamera * pICamera, 
AFESize * pSize 
) 














Parameters: 
piCamera Pointer to ICamera Interface 
pSize Size of the picture 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM SIZE LIST details. 


See Also: 


ICAMERA GetParm() 
CAM PARM SIZE LIST 


Return to the List of functions 
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ICAMERA SetVideoEncode() 


Description: 
This function sets the active video/image encoding type used to encode the recorded 
snapshot/movie. 


Prototype: 

int ICAMERA SetVideoEncode 
( 
ICamera * pICamera, 
AEECLSID cls, 
uint32 dwExtra 


) 




















Parameters: 
piCamera Pointer to ICamera Interface. 
cls Encoding class ID 
CAM ENCODE RAW, AEECLSID JPEG 
AEECLSID MEDIAMPEG4, etc. 
dwExtra Extra info regarding the encoding like sub formats. 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM VIDEO ENCODE details. 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA SetZoom() 


Description: 
This function sets the zoom of the camera. 


Prototype: 


int ICAMERA SetZoom 
( 
ICamera * pICamera, 
int32 nValue 


) 





Parameters: 
piCamera Pointer to ICamera Interface. 
nValue Zoom value 


Return Value: 
SUCCESS: Successful. Operation completed. 
CAM PENDING: Result returned via the registered callback 
EBADPARM: Bad parm 
ENOMEMORY: Not enough memory 
EBADSTATE: Cannot set parm in the current state 
EUNSUPPORTED: Parm not supported by the class 


Comments: 


For ICAMERA GetParm() information, see Camera Control Parameters for 
CAM PARM ZOOM details. 


ICAMERA GetParm() with CAM PARM ZOOM, returns AEEParminfo that specifies 
the zoom info. 


See Also: 
ICAMERA GetParm() 
Return to the List of functions 
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ICAMERA Start() 


Description: 
This function starts camera operation in preview, snapshot, or movie mode. 


Prototype: 


int ICAMERA Start 
( 
ICamera * pICamera, 
int 16 nMode, 
uint32 dwParam 
); 





Parameters: 
piCamera Pointer to ICamera Interface 
nMode CAM MODE PREVIEW 
CAM MODE SNAPSHOT 
CAM MODE MOVIE 
dwParam Reserved 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
EBADPARM: Bad parm is passed 
ENOMEMORY: Not enough memory 
EBADSTATE: Start cannot be done in current state 


Comments: 


Allthe events that originate due to this API and due to the following API will be reported 
via the user-specified callback. 


ICAMERA Preview() 
ICAMERA RecordSnapshot() 
ICAMERA RecordMovie() 
ICAMERA Stop() 
ICAMERA Pause() 
ICAMERA Resume() 
In the callback, AEECameraNotify, 
nCmd = CAM CMD START and nSublmd = nMode. 


See Also: 


AEECameraNotify 
ICAMERA Start() 
ICAMERA Stop() 
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ICAMERA Pause() 
ICAMERA Resume() 
ICAMERA GetFrame() 
ICAMERA Preview() 
ICAMERA RecordMovie() 
ICAMERA RecordSnapshot() 


Return to the List of functions 


ICamera Interface 
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ICAMERA Stop() 


Description: 
This function stops the current camera operation and puts itin Ready state. 





Prototype: 

int ICAMERA Stop (ICamera * pICamera); 
Parameters: 

piCamera Pointer to ICamera Interface. 


Return Value: 
SUCCESS: Command accepted 
EFAILED: General failure 
ENOMEMORY: Not enough memory 
EBADSTATE: Stop cannot be done in current state 


Comments: 
This function results in CAM STATUS DONE status callback. 


In the callback, AEECameraNotify, nCmd = CAM CMD START and nSubCmd = 
CAM MODE PREVIEW/CAM MODE MOVIE. 


See Also: 


ICAMERA Start() 

ICAMERA Preview() 
ICAMERA RecordMovie() 
ICAMERA RecordSnapshot() 


Return to the List of functions 
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IDIB Interface 


IDIB is a structure and an interface. IDIB inherits all of the member functions of IBitmap, so an 
IDIB may be used as an IBitmap by type casting. The IDIB TO IBITMAP in-line function is 
supplied for type safe casting. Unlike other BREW interfaces, IDIB also has public data 
members. These data members can be used to efficiently read or modify image data. 


An application typically obtains an IDIB pointer from an IBitmap pointer by calling 

IBITMAP Querylnterface() with the class ID AEECLSID DIB. Not all IBitmap classes support 
IDIB, and in those cases the QueryInterface function will return an error code. On success, an 
IDIB pointer is returned, which must be released when the caller has finished using it. 


A bitmap consists of a 2-dimensional array of pixels. IDIB contains members that indicate 
where in memory the pixels are, and how the pixel values are to be interpreted. 


Pixel array structure 


The locations and sizes of pixels in the pixel array are described by the pBmp, nPitch, and 
nDepth members. The nPitch field specifies the distance (in bytes) from the beginning of any 
row to the beginning of the next row. Pitch is typically function of the bitmap width, the padding 
being applied, and whether itis a top-down or bottom-up bitmap. A bottom-up bitmaps will 
have a negative pitch value. 


Users of an IDIB should honor the nPitch value and make no assumptions about padding or 
direction in the bitmap.The pBmp parameter points to the top scan line, y=0, in the memory 
buffer that holds the pixel data of a DIB. For a top-down DIB, the pointer points to the first row 
of the buffers pixel data. For a bottom-up DIB, the pointer points to the last row of the buffers 
pixel data. 


Usage example: 


For a bitmap of color depth 8 (one byte per pixel), width of 9, and height of 10, the following 
representations are possible (among others): 
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nPitch pBmp Start of bit array 
Top-down BMP file 12 0 
Bottom-up BMP file -12 96 
Top-down packed bitmap 9 0 
Bottom-up packed bitmap -9 72 


In all of these cases, and in fact for any 8-bit DIB, the code for reading a pixel remains the 
same: 


COLORVALUE = pdib->pBmp[ y * pdib->nPitch + x ] 





Alignment: Rows typically starts at 32-bit boundaries, but alignment is not guaranteed except 
in two cases. When nDepth is 32, rows should be 32-bit aligned, and when nDepth is 16, each 
row must be aligned on a 16-bit boundary. 


Within a row, the left most (x=0) pixel begins at the most significant bit of the fits byte. Pixels 
are packed, bitwise, and split across bytes if necessary. 1, 2, 4,8, and 16 bit bitmaps minimize 
splitting of pixel values across bytes, and yield the most efficiency. While possible and well- 
defined, sizes that tend to map irregularly to byte boundaries (like 3 or 12) will lead to reduced 
efficiency. 


Pixel values 


The type NativeColor is defined to represent values stored in pixels in the pixel array. Palette 
information (cntRGB and pRGB, or alternatively nColorScheme) describes how pixel values 
map to red, green, and blue intensity values. 


When cntRGB is non-zero, the pixel values are treated as indices into the palette, which is an 
array of 32-bit R-G-B color values. (See pRGB.) When nColorScheme is non-zero, it 
identifies a mapping of pixel values to R-G-B values. This can be thought of as a hard-coded 
palette. (See nColorScheme.) 


When both cntRGB and nColorScheme are zero, the color values of the bitmap are 
undefined. 


Note that this mapping between pixel values and colors is somewhat independent of pixel size. 


A 4096 color bitmap requires 12 bits to represent all color values, but these may be stored in 
12-bit (a packed representation) or 16-bit pixels (unpacked). 
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Transparency is a special case in interpreting pixel values. For operations that support 
transparency, such as IBITMAP BltIn() when called with the AEE RO TRANSPARENT raster 
operation, pixels whose values match the transparent color (ncTransparent) are treated as 
transparent, which means that the corresponding pixels in the destination are left unmodified. 
ncTransparent is a NativeColor value, and the matching is performed on pixel values, not on 
the corresponding R-G-B intensities. 


Palette Map 


The pPaletteMap member is provided as a way for driver software to cache information 
computed from the bitmap's palette. This is not simply a function of the palette -- it depends 
also on the graphics algorithm, and any other bitmaps with which the DIB might interact. This 
member is set to NULL when there is no palette mapping object associated with the IDIB. 


Every IDIB implementation must ensure that the pPaletteMap object (if set) is released when 
the IDIB itself is deleted. The IDIB FlushPalette() macro performed this task. 


Any pPaletteMap must be released whenever an IDIB is modified such that the interpretation 
of pixel values are affected (i.e. when cntRGB, pRGBI], nColorScheme, or ncTransparent 
are modified). Otherwise, a graphics algorithm might proceed to use stale data or perhaps 
even corrupt memory on a subsequent call. 


Generally, users can ignore this value unless they modify a DIB palette's data after ithas been 
used (i.e. graphics operations, such as IBitmap member functions, have been used on it). In 
that case, IDIB FlushPalette() must be called. 


Software Support 


IDIB presents a wide range of possibilities for bitmap layouts, but practical constraints limit the 
number of formats that are supported by other software in the handset. Of the layouts that are 
supported, not all of those are fully optimized. These limitations can differ from handset to 
handset. The purpose of DIBs, however, is to communicate bitmap data to or from the graphics 
driver, so the target device's level of support for particular formats is important to application 
software. Here are some general guidelines: 


* Each handset's primary display (whether monochrome, grey scale, or color) should 
support blitting from palette-based 1-, 2-, 4-, and 8-bit DIBs. 
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* Color mapping generally is done in an expedient fashion rather than the most 
accurate fashion. 1-bit and 8-bit operations should be particularly well optimized. 
Additionally, 16-bit handsets will support 16-bit DIB formats using either 
IDIB COLORSCHEME 555 or IDIB COLORSCHEME, 565 color schemes, but 
blitting a 5-5-5 DIB to a 5-6-5 device, or vice versa, will incur a performance penalty. 


8-bit palette-based DIBs should work well with all color displays, and are much smaller than 
16-bitimages, so are recommended for color images. Since each 8-bit image can have its own 
selection of 256 colors, color accuracy should not be a problem. 


List of Header files to be included 

The following header file is required: 
AEEBitmap.h 

List of functions 


Functions in this interface include: 


IDIB AddRef() 

IDIB FlushPalette() 
IDIB Querylnterface() 
IDIB Release() 

IDIB TO IBITMAP() 


The remainder of this section provides details for each function. 
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IDIB AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IDIB Release() 
Return to the List of functions 
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IDIB FlushPalette() 


Description: 


This macro is used to release the pPaletteMap member of the IDIB structure. This is 
necessary whenever the DIB's palette is modified, since the information cached in the 
palette map will no longer be valid. This macro first check whether pPaletteMap is 
NULL. If so, it does nothing. Otherwise, it calls the palette map's release function, and 
sets pPaletteMap to NULL. 


Prototype: 


IDIB FlushPalette(pdib) if ((pdib)->pPaletteMap) 
(IQI Release ((pdib)->pPaletteMap) ; 
(pdib)->pPaletteMap = 0;) 
Parameters: 
pdib [in] Pointer to IDIB structure. 


Return Value: 
no return value 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDIB Querylnterface() 


Description: 
This function is inherited from IQI Querylnterface(). 


See Also: 
IDIB 


Return to the List of functions 
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IDIB Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IDIB AddRef() 
Return to the List of functions 
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IDIB TO IBITMAP() 


Description: 
This function provides type safe casting from IDIB Interface pointers to IBitmap 
Interface pointers. This function should be used when passing an IDIB interface to an 
IBitmap function. This is safer than a simple cast, since the compiler will verify the 


pointer type. 
Prototype: 

“inline IBitmap *IDIB TO IBITMAP (const IDIB *pIDIB); 
Parameters: 

piDIB Pointer to an IDIB interface. 


Return Value: 
Returns pIDIB cast to an IBitmap*. 


Comments: 
None 


See Also: 
IDIB 
Return to the List of functions 
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IDNS Interface 


IDNS provides a way to perform DNS (Domain Name System) queries. IDNS provides a more 
general interface to the DNS client than INETMGR GetHostByName(). Alternate request 
types and compound queries are supported. The DNS client will keep track of DNS servers 
and handle retransmission and time-outs. IDNS converts domain names to the DNS protocol 
representation, and provides a method for decoding compressed domain names in the 
response. The user is responsible for specifying the content of DNS Question records, locating 
the data of importance in the response, and interpreting those values. UDP is the only 
transport supported. Requests and responses are limited to 512 bytes. 


List of Header files to be included 


The following header file is required: 


aeedns.h 
List of functions 


Functions in this interface include: 


IDNS AddQuestion() 
IDNS AddRef() 

IDNS GetResponse() 
IDNS ParseDomain() 
IDNS Querylnterface() 
IDNS Release() 

IDNS Start() 


The remainder of this section provides details for each function. 
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IDNS AddQuestion() 


Description: 


This function adds a question to the set of question records in the request. This must 
be called before Start() is called. This can be called multiple times to construct a 
request message consisting of multiple question records. 


Prototype: 


int IDNS AddQuestion ( 

IDNS *pIDNS, 
ABEDNSType nType, 
ABEDNSCIlass nClass, 
const char *pszDomain 


) 




















Parameters: 
nType DNS question type 
nClass DNS class 


pszDomain 'Zero-terminated string representing a domain name in dotted notation. 
Single dot terminators as in “example.com.” are acceptable and treated 
identically to domain names without a terminating dot. NOTE: Domain 
search paths and relative domain names are not supported.) 


Return value: 
SUCCESS means that the question was appended to the request message. 


EFAILED, if the new question would make the DNS message exceed the maximum 
size (512 bytes for DNS over UDP). 


EBADPARM, if the domain name is malformed. 


AEE NET EINVAL, if IDNS is not in the proper state for questions to be added. 
Questions cannot be added after Start() has been called. 


Other errors may be returned; the caller should verify that IDNS AddQuestion() 
succeeded. 


Comments: 


All domains are treated as fully-qualified domains by IDNS. There is no domain suffix 
search list; suffixes are never attached to the provided domain string. Colon (:), slash 
(/) and comma (,) characters do not delimit the domain name as in 

INETMGR GetHostByName(). When constructing a question record, IDNS does not 
use the compressed form of domain names. 


See Also: 
AEEDNSType 
AEEDNSClass 
Return to the List of functions 
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IDNS AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IDNS Release() 
Return to the List of functions 
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IDNS GetResponse() 


Description: 


This function is to be called to obtain the DNS response after the query completes. On 
success, it returns a pointer to a structure with the description of the DNS response. 
Response data includes pointers to structures; the referenced memory will be valid 
only for the lifetime of the IDNS object. None of those pointers should be retained or 
used after the IDNS interface has been released. 














Prototype: 

int IDNS GetResponse (IDNS *pIDNS, const AEEDNSResponse **pResp); 
Parameters: 

pIDNS [in] Pointer to the IDNS Interface object 

pResp [out] Pointer to a structure describing the response. 


Return value: 


SUCCESS: A response message was received from a DNS server; *pResp describes 
the result. Success here does not imply that the query was successful, just that a 
response was received. The application must inspect the AEEDNSResponse structure 
to determine whether the requested data is present in the response. 


In all error cases, *pResp will point to an empty AEEDNSResponse structure. No 
assumptions should be made about the contents. 


Error codes include: 


ENOMEMORY if memory allocation failure prevented request or response 
AEE NET ETIMEDOUT if retransmission time-out (no servers responded) 
AEE NET ENETNONET, if socket-level error occurs 


Comments: 
None 


See Also: 
AEEDNSResponse 
Return to the List of functions 
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IDNS ParseDomain() 


Description: 


This function converts a DNS representation of a domain name into a 
zero-terminated string with dot (.) or dash (-) delimiter. 


Prototype: 
char *IDNS *ParseDomain(IDNS *pIDNS, const byte *pbyDomain, int *pcb); 
Parameters: 
pIDNS Pointer to the IDNS Interface object 
pbyData Pointer to the start of the domain name. This pointer must point into the DNS 
response data as described by an AEEDNSItem record. This can be used to 
decode pbyDomain values, or to decode values within the pbyDatal[] array. 
pcb Pointer to value to hold the number of bytes occupied by the domain name (in 


the source byte array, not in the resulting string). In the case of a malformed 
domain name, *pcb will be set to zero. If pcb==NULL, it will be ignored. 


Return value: 


Zero-terminated string giving the host name, or NULL on failure. Domain names are 
returned in dotted notation, with no terminating dot character at the end. Failure may 
be due to an allocation failure or a malformed domain name; *pcb can be used to 
distinguish between the two. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDNS Querylnterface() 


Description: 
This function is inherited from IQI Querylnterface(). 


See Also: 


IDNS 
Return to the List of functions 
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IDNS Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IDNS AddRef() 
Return to the List of functions 
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IDNS Start() 


Description: 
This function starts the query, and schedule callback to be called. In order to prevent 
the callback from firing, and to cancel the operation, the user should release all 
references to the IDNS. Start() should not be called twice. 


Prototype: 
IDNS Start (IDNS *pIDNS, PFNNOTIFY pfn, void *pcxt); 
Parameters: 
pIDNS Pointer to the IDNS Interface object 
pfn Function to be called after the operation completes. This will only be called if 
the operation starts successfully (i.e. when Start() returned SUCCESS). 
pv Void pointer to be passed to the pfn() when it is called. 


Return value: 
error code: 


SUCCESS, if the operation started. This should always succeed when called the 
first time. 
AEE NET EINVAL, if this function is called more than once. 


Comments: 
Releasing all references to the IDNS object will cancel the operation and prevent the 
callback from being called. 


See Also: 
PFNNOTIFY 
Return to the List of functions 
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[Download Interface 


This interface provides access to BREW application and file download mechanisms. It is for 
use ONLY by QUALCOMM, Handset Manufacturer and selected partners. 


The IDownload interface consists of interface functions to query list(s) of application 
categories and/or items, download items and remove/disable items. The interface has been 
developed on the IWeb interface and shields the developer from all of the complexities 
involved in downloading applications. 


List of functions 


Functions in this interface include: 


IDOWNLOAD Acquire() 
IDOWNLOAD AutoDisable() 
IDOWNLOAD Cancel() 

IDOWNLOAD CheckltemUpgrade() 
IDOWNLOAD CheckUpgrades() 
IDOWNLOAD Continue() 
IDOWNLOAD Credit() 
IDOWNLOAD Delete() 
IDOWNLOAD Enum() 
IDOWNLOAD EnumRaw() 
IDOWNLOAD Get() 

IDOWNLOAD GetADSCapabilities() 
IDOWNLOAD GetADSList() 
IDOWNLOAD GetAllApps() 
IDOWNLOAD GetAppIDList() 
IDOWNLOAD GetAppIDListEx() 
IDOWNLOAD GetAutoDisableList() 
IDOWNLOAD GetAvailable() 
IDOWNLOAD GetCategory() 
IDOWNLOAD GetCategoryList() 
IDOWNLOAD GetConfigltem() 
IDOWNLOAD GetEULA() 
IDOWNLOAD GetHeaders() 
IDOWNLOAD Getlteminfo() 
IDOWNLOAD GetltemList() 
IDOWNLOAD GetModilnfo() 
IDOWNLOAD GetSize() 
IDOWNLOAD GetSizeEx() 
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IDOWNLOAD Lock() 
IDOWNLOAD LogEnumtinit() 
IDOWNLOAD LogEnumNext() 
IDOWNLOAD OnsStatus() 
IDOWNLOAD Restore() 
IDOWNLOAD Search() 
IDOWNLOAD SetADS() 
IDOWNLOAD SetHeaders() 
IDOWNLOAD SetSubscriberlD() 


The remainder of this section provides details for each function. 
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IDOWNLOAD Acquire() 


Description: 
Asynchronously downloads an application and registers a billing record with the server 
for the associated price It value. 


Prototype: 


void IDOWNLOAD Acquire 
( 
IDownload * po, 
DLITEMID id, 
DLPRICEID idPrice, 
PENDLCOMMAND pn, 
void * pcxt 


) 








Parameters: 
po Pointer to the IDownload interface object. 
id Application ID. 
idPrice Price value ID. 
pfn Pointer to the handle command function 
pext Pointer to the user define data 


Return Value: 
Upon completion, the callback specified is called with the associated completion 
code/error value. A code of O indicates success. 


Comments: 
None 


Side Effects: 


This call will attempt to initiate a network connection. 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD AutoDisable() 


Description: 


This function is uaed to auto-disable applications. Applications are"auto-disabled" in 
the following order... 


1) Listis scanned and applications are marked for "auto-disable" in least-recently- 
usedorder until enough space is recovered. 


2) This sub-list is scanned backward and applications are "unmarked" if the space 
thenecessary space can be achieved without them. 


This covers the following example: 
Space Required: 33K 
App A 10K 
App B 11K 
App C 23K 
After Step 1, all three applications are marked for disable. 


After Step 2, only App A and App C are marked. App B is no longer marked because 
it can be left enabled and the space can still be recovered. 





Prototype: 

int IDOWNLOAD AutoDisable(IDownload * po, DLITEMID 41ID); 
Parameters: 

po [in] Pointer to the IDownload interface object. 

id [in] Item ID for the operation. 


Return Value: 
SUCCESS - If applications are successfully auto-disabled 
EFSFULL - Insufficient FS storage space (dwFSAvail < dwFSRequired) 


ENOMEMORY - Insufficient contiguous RAM for the item (dwRAM < 
dwEstRAMRequired) 


Comments: 
None 


See Also: 
IDOWNLOAD GetAutoDisableList() 
IDOWNLOAD Lock() 
Return to the List of functions 
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IDOWNLOAD Cancel() 


Description: 
Cancels all pending IDOWNLOAD operations. 


Prototype: 

void IDOWNLOAD Cancel (IDownload * po) 
Parameters: 

po [in] Pointer to the [Download interface object. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD CheckltemUpgrade() 


Description: 
This function checks whether there is an upgrade for the given ItemlD. 


Prototype: 

void IDOWNNLOAD CheckItemUpgrade 
( 
IDownload * po, 
DLITEMID id, 
PENDLENUM pfn, 
void * pcxt 
); 








Parameters: 
po Pointer to the IDownload interface object. 
id Item ID for the operation. 
pfn User callback to be called for item retrieved. 
pext User context handle passed as first parameter to callback. 


Return Value: 
None 


Comments: 
None 


See Also: 
IDOWNLOAD CheckUpgrades() 
Return to the List of functions 
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IDOWNLOAD CheckUpgrades() 


Description: 
This function checks for upgrades for all the items. 


Prototype: 
void IDOWNNLOAD CheckUpgrades 
( 
IDownload * po, 
PENDLENUM pÊfn, 
void * pcxt 
); 





Parameters: 
po Pointer to the IDownload interface object. 
pfn User callback to be called for item retrieved. 
pext User context handle passed as first parameter to callback. 


Return Value: 
None 


Comments: 
None 


See Also: 
IDOWNLOAD CheckltemUpgrade() 
Return to the List of functions 
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IDOWNLOAD Continue() 


Description: 
This method is called to indicate how the download engine should process an in- 


progress request. It is intended for use following a status callback of type 
DEVT Al ASK, DEVT Al DENY, DEVT Al SUCCESS, DEVT Al FAILURE. 


Prototype: 

void IDOWNLOAD Continue (IDownload * po, boolean bContinue) 
Parameters: 

po [in] Pointer to the [Download interface object. 


bContinue [in] TRUE to continue. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD Credit() 


Description: 


This function credits the user. 


Prototype: 


void IDOWNLOAD Credit 


( 


IDownload * po, 
const char * psz, 
PENDLCOMMAND pfn, 
void * pcxt 


); 


Parameters: 
po 
psz 
pfn 


pext 


Return Value: 


None 


Comments: 
None 


See Also: 
None 


Pointer to the IDownload interface object. 
Credit-back access ticket. 
User callback to be called for item retrieved. 


User context handle passed as first parameter to callback. 


Return to the List of functions 
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IDOWNLOAD Delete() 


Description: 
Removes application files from persistent memory. If the boolean "bRemoveaAllFiles" 
parameter is specified, all files and sub-directories for the application are removed. If 
not, the main resource and module files are removed. 


Prototype: 


int IDOWNLOAD Delete 
( 
IDownload * po, 
DLITEMID id, 
boolean bRemoveAllFiles 
) 





Parameters: 
po [in] Pointer to the IDownload interface object. 
id [in] Application ID. 
bRemoveaAllFiles [in] Indicates whether all files should be removed. 


Return Value: 
SUCCESS if the item is disabled or removed. 
EBADPARM if the itemnot found. 
EITEMBUSY if the itemspecified is running/active. 
EBADSID if the wrong subscriber attempts to remove item 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD Enum() 


Description: 


This is the post-1.01 mechanism that supports advanced category and item 
enumeration. The PFNDLENUM function callback is called for each item retrieved with 
a pointer to the item retreived. When the operation is complete, the callback is called 
one final time with a NULL DLEnumitem pointer. 


Enumeration of the base/root category is initiated by calling the function with the 
DL CATEGORY ROOT item ID value. 


Calls to this function passing an item ID for an item of type DLI CATEGORY will 
enumerate the items inside that category. This allows the caller to enumerate the list 
of categories and applications using a mechanism similar to that used for file/directory 
enumeration. 


A call to this function for an item of type other than DLI CATEGORY will return the 
DLiteminfo for that particular item. 

A call to this mechanism cancels any other pending calls. 

NOTE: Caching of information is provided inside the protocol. There is no need to 


cache information. Information will not be retrieved from the network unless the cache 
is invalid. 


Prototype: 


void IDOWNLOAD Enum 
( 
IDownload * po, 
DLITEMID id, 
PENDLENUM pfn, 
void * pcxt 


) 





Parameters: 
po [in] Pointer to the [Download interface object. 
id [in] Item ID for the operation. 
pfn [in] User callback to be called for each item retrieved. 
pext [in] User context handle passed as first parameter to callback. 


Return Value: 


None 


Comments: 


None 


See Also: 


IDOWNLOAD EnumRaw() 
Return to the List of functions 
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IDOWNLOAD EnumRaw() 


Description: 


This is the post-1.0.1 mechanism that supports advanced category and item 
enumeration. Returns all possible purchasing method for every known application with 
out any checks such as inconsistent purchasing methods, if itis an already resident 
app, etc.,. The PFNDLENUM function callback is called for each item retrieved with a 
pointer to the item retreived. When the operation is complete, the callback is called one 
final time with a NULL DLEnumitem pointer. 


Enumeration of the base/root category is initiated by calling the function with the 

DL CATEGORY ROOT item ID value. Calls to this function passing an item ID for an 
item oftype DLI CATEGORY will enumerate the items inside that category. This allows 
the caller to enumerate the list of categories and applications using a mechanism 
similar to that used for file/directory enumeration.A call to this function for an item of 
type other than DLI CATEGORY will retum the DLIteminfo for that particular item.A 
call to this mechanism cancels any other pending calls. 


NOTE: Caching of information is provided inside the protocol. There is no need to 
cache information. Information will not be retrieved from the network unless the cache 
is invalid. 


Prototype: 


void IDOWNLOAD EnumRaw 
( 
IDownload * po, 
DLITEMID id, 
PENDLENUM pÊfn, 
void * pcxt 
); 














Parameters: 
po [in] Pointer to the IDownload interface object. 
id [in] Item ID for the operation. 
pfn [in] User callback to be called for each item retrieved. 
pext [in] User context handle passed as first parameter to callback. 


Return Value: 


None 


Comments: 


None 


See Also: 


IDOWNLOAD Enum() 
Return to the List of functions 
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IDOWNLOAD Get() 


Description: 
Asynchronously downloads an application from the server. This involves getting the 
package file, verifying it, and extracting the content files. The application's MIF file is 
the last file written to the file system. 


Prototype: 


void IDOWNLOAD Get 
( 
IDownload *po, 
DLITEMID id, 
PENDLCOMMAND pn, 
void * pcxt 
); 





Parameters: 
po Pointer to the IDownload interface object. 
id Application ID 
pfn Callback function pointer 
pctxt Pointer to be passed back in the callback function 


Return Value: 


Upon completion, the callback specified is called with the associated completion 
code/error value. A code of O indicates success. 


Comments: 
During operation several events are posted to the client application class specified by 
clsiD. These events are: 


EVT DOWNLOAD COMPLETE to nofity client that the download has finished, either 
successfully or not. Will be posted once. 


Side Effects: 


This call will attempt to initiate a network connection. 


See Also: 
IDOWNLOAD Acquire() 
Return to the List of functions 
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IDOWNLOAD GetADSCapabilities() 


Description: 
This function returns the ADS capabilities. This allows the application to determine 
whether some menu items (such as search) should be displayed. 


Prototype: 

void IDOWNLOAD GetADSCapabilities(IDownload * po) 
Parameters: 

po [in] Pointer to the [Download interface object. 


Return Value: 
ADS CAP XXXX flags 
O = No ADS server connected 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetADSList() 


Description: 


This function returns a list of ADS servers. Itis supported only on test enabled 
handsets. Itis unsupported in production releases. 





Prototype: 

ADSInfoEntry * IDOWNLOAD GetADSList (IDownload * po, int * pnCount) 
Parameters: 

po [in] Pointer to the [Download interface object. 

pnCount [in/out] Pointer to fill with count of servers. If NULL, the existing list is 


freed. 


Return Value: 
Pointer to list of ADS servers or NULL if unsupported. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetAllApps() 


NOTE: This function is a Version 1.0 legacy function. Use IDOWNLOAD Enum() 
instead. 


Description: 
Retrieves all the known applications that has been installed 


Prototype: 

void IDOWNLOAD GetAllApps (IDownload *po); 
Parameters: 

po Pointer to the IDownload interface object. 


Return Value: 
None 


Comments: 
Upon completion the callback is called with the appropriate error value. 
If the error code is O (success), the item list pointer provided is 
valid. 


See Also: 
IDOWNLOAD GetltemList() 
Return to the List of functions 
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IDOWNLOAD GetAppIDList() 


Description: 
This function returns a O-terminated list of application IDs. Each DLITEMID can be 
used to query specific information about the application via the 
IDOWNLOAD GetModilnfo function. 





Prototype: 

DLITEMID * IDOWNLOAD GetAppIDList (IDownload * po) 
Parameters: 

po [in] Pointer to the [Download interface object. 


Return Value: 


On SUCCESS, returns a 0-terminated list of DLITEMID values. This list is valid until a 
subsequent call is made to IDOWNLOAD GetApplIDList or the interface is released. 


On FAILURE, returns NULL. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetAppIDListEx() 


Description: 
This function returns a NULL terminated list of application IDs including those that are 
protected (modules that cannot be deleted by the user). Each DLITEMID can be used 
to query specific information about the application via the DOWNLOAD GetModlnfo() 








function. 
Prototype: 

DLITEMID * IDOWNLOAD GetAppIDListEx (IDownload *po); 
Parameters: 

po [in] Pointer to the IDownload interface object. 


Return Value: 
SUCCESS: Returns a NULL terminated list of DLITEMID values. 
FAILURE: Returns NULL 


Comments: 


The list returned is valid until a subsequent call is made to 
IDOWNLOAD GetAppIDListEx() or the interface is released. 


See Also: 
IDOWNLOAD GetAppIDList() 
Return to the List of functions 
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IDOWNLOAD GetAutoDisableList() 


Description: 


This function retrieves the list of entries that can be auto-disabled. The idWant/dwExtra 
parameters can be specified in order to mark those items that would be candidates to 
disable based upon size and date/time last used. 


The list is returned sorted in least-recently used order. By using DLITEMID, this call is 
equivalent to the IDOWNLOAD AutoDisable() function without the function 
automatically disabling the items. 


Prototype: 


DLDisableEntry * IDOWNLOAD GetAutoDisableList 
( 
IDownload * po, 
DLITEMID idWant, 
uint32 dwExtra, 
int * pnCount, 
int * pnErr 


) 














Parameters: 
po [in] Pointer to the IDownload interface object. 
idWant [in] ID of item that may be downloaded. O if all entries 
dwExtra [in] Extra number of bytes desired. 
pnCount [out] Number of entries in the list 
pnErr [out] Pointer to error 


Return Value: 
Returns the list that can be auto-disabled 
NULL - Indicates an error *pnErr: 
SUCCESS - idWant + dwExtra size is available in file system 
EFSFULL - idWant + dwExtra cannot be satisified by disable 


Comments: 
None 


See Also: 
IDOWNLOAD Lock() 
Return to the List of functions 


242 


Era [Download Interface 


IDOWNLOAD GetAvailable() 


Description: 
This method is called to populate available file and RAM space for 
potential downloads. 


Prototype: 

int IDOWNLOAD GetAvailable(IDownload * po, DLSizeInfo * psi); 
Parameters: 

po [in] Pointer to the IDownload interface object. 

psi [out] Size information 


Return Value: 
AEE SUCCESS if successful 


EFSFULL - Insufficient FS storage space 
(dwFSAvail < dwFSRequired) 


ENOMEMORY - Insufficient contiguous RAM for the item 
(dAWRAM < dwEstRAMRequired) 


EOUTOFNODES - Insufficient file handles available 
(nFilesAvail < nEstFileRequired) 


EBADPARM - If psi is NULL or the package is invalid 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetCategory() 


NOTE: This function is a Version 1.0 legacy function depricated. Use 
IDOWNLOAD Enum() instead. 


Description: 
Asynchronously retrieves the list of categories for the specified category ID. 


Prototype: 


void IDOWNLOAD GetCategory 
( 
IDownload *po, 
DLCATID id, 
PENDLITEMLIST pÊfn, 
void * pcxt 
); 





Parameters: 
po Pointer to the IDownload interface object. 
id Category ID (0 - all) 
pfn Pointer to callback function. 
pcetxt Pointer to user data context passed as first argument to function. 


Return Value: 
None 


Comments: 
Upon completion the callback is called with the appropriate error value. 
If the error code is O (success), the item list pointer provided is 
valid. 


Side Effects: 


This call will attempt to initiate a network connection. 


See Also: 
IDOWNLOAD Enum() 
Return to the List of functions 
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IDOWNLOAD GetCategoryList() 


NOTE: This function is a Version 1.0 legacy function depricated. Use 
IDOWNLOAD Enum() instead. 


Description: 
Asynchronously retrieves the list of categories available on the server. 


Prototype: 
void IDOWNLOAD GetCategoryList 
( 
IDownload * po, 
PENDLCATEGORYLIST pfn, 
void * pcxt 


) 





Parameters: 


po [in] Pointer to the [Download interface object. 


Return Value: 
Upon completion, the callback is called with the appropriate error value. 
If the error code is O (success), the category list pointer provided is valid. 


Comments: 
None 


Side Effects: 


This call will attempt to initiate a network connection. 


See Also: 
IDOWNLOAD Enum() 
Return to the List of functions 
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IDOWNLOAD GetConfigltem() 


Description: 
This function retrieves the device configuration information related to 
the download services. 


Prototype: 


int IDOWNLOAD GetConfigItem 
( 
IDownload * po, 
int 2, 
void * pItem, 
int nSize 


Dj 


Parameters: 
po [in] Pointer to the IDownload interface 
object. 
Po [in] is fully consistent with OEM GetConfig() changes. 
CFGI AUTOSTART, AEECLSID - Auto-Started Applet 
(AEE Init()) 
CFGI BUSY CURSOR OFFSET, Position of hourglass (AEERect *) 
char CFGI CARDID Unique identifier that identifies the 
attached card. The input buffer for this 
will be the size returned by 
CFGI CARDID LEN 
int CFGI CARDID LEN Size in bytes of the CARDID (For e.g., 
RUIM./SIM) 
CFGI CLOSE KEYS OEMCloseKeys * (see structure 
below) 
CFGI DATA NETWORK OEMDataNetwork * 
CFGI DEBUG KEY OEMDebugkKey * see 


OEM GetConfig() 
CFGI DISALLOW DORMANCY boolean, if TRUE, disallow dormancy, 


CFGI DNS IP1 32-bit IP, Domain Name Server(1) in 
network byte-order 
CFGI DNS IP2 32-bit IP, Domain Name Server(2) in 


network byte-order 


CFGI DORMANCY NO SOCKETS boolean, whether to hold PPP (go 
dormant) even if no sockets are open 


CFGI DOWNLOAD AEEDownloadiInfo 
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uint32 
uint32 
uint32 
uint32 


MIFFS 
Limit 


[Download Interface 


CFGI DOWNLOAD BUFFER, 


CFGI DOWNLOAD FS INFO, 
CFGI FILE CACHE INFO, 
CFGI FIRST OEM=CFGI MAX 


CFGI GPSONE LOCK, 

CFGI GPSONE SVRIP, 

CFGI GPSONE SVRPORT, 
CFGI GPSONE TRANSPORT, 
CFGI HTTP BUFFER, 


CFGI MAX, 
CFGI MAX DISPATCH TIME, 
CFGI MIN IDLE TIME, 


CFGI MOBILEINFO, 
CFGI MODULE FSLIMIT, 


CFGI NET CONNTIMEOUT, 


CFGI PROVISION FIRST=0x1000, 
CFGI PROVISION LAST=0x2000, 
CFGI SCREEN SAVER, 
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Size in bytes to buffer data during 
download before calling fs write 
(default 10K) 


DLitemSize * (Fill dwFSAvail, 
dwFSSize) 


OEMFileCachelnfo * (see structure 
below) 


OEM added config items should start 
at this value 


GPS lock 

GPS server IP address 

GPS server IP port 

OEM GPS transport (IP, Data burst) 


Size in bytes of HTTP read buffer 
(default 4K) 


Holds max AEE value, not a function 


Maximum time BREW should spend in 
the dispatcher before relinquishing 
control (default = 250 msecs) 


Minimum time BREW must relinquish 
from dispatcher (default = 35 msecs) 


AEEMobileInfo 


This identifies the maximum files and 
maximum space that can be used up 
by a module. 


The default value for these are set to 
the maximum permissible limit. 


MIFFSLimit is broken down into the 
following subcomponents: 


Subcomponents - Type - Description 


wMaxrFiles - uint16 - Maximum 
number of files in EFS this module is 
allowed to create 


dwMaxSpace - uint32 - Maximum EFS 
space this module is allowed to 
consume 


time in milliseconds! to wait for 
connect() 


Offset to build dependent items 
End of build dependent items 


AEE ScreenSaverinfo * 
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CFGI SLEEP TIMER RESOLUTIO, Timer resolution during when 
processor/os is in SLEEP mode 
(default = 1.2 seconds) 


CFGI SUBSCRIBERID, 32-byte ASCIIZ 


CFGI SUBSCRIBERID LEN Size in bytes of subscriber ID. The 
default used if error returned. The 
NULL terminator is counted in the 
count returned 


uint32 CFGI SYSMEM SIZE Size in bytes reserved to the system in 
low-memory (default = 2K) 


Return Value: 
None 


Comments: 
None 


See Also: 
OEM GetConfig() 
Return to the List of functions 


248 


Era [Download Interface 


IDOWNLOAD GetEULA() 


Description: 


This function gets the EULA for the given ItemlD. When the text is fetched, it invokes 
the callback function passed as argument to this function. 


Prototype: 


void IDOWNLOAD GetEULA 
( 
IDownload * po, 
DLITEMID id, 
PENDLTEXT pÍfn, 
void * pcxt 
); 

















Parameters: 
po Pointer to the IDownload interface object. 
id Item ID for the operation. 
pfn User callback to be called for item retrieved. 
pext User context handle passed as first parameter to callback. 


Return Value: 
None 


Comments: 
None 


See Also: 
PFNDLTEXT 
Return to the List of functions 
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IDOWNLOAD GetHeaders() 


Description: 
Returns the current HTTP headers set via the IDOWNLOAD SetHeaders() call. 


Prototype: 

const char * IDOWNLOAD GetHeaders (IDownload * po) 
Parameters: 

po [in] Pointer to the [Download interface object. 


Return Value: 
NULL: No headers set 
Header strings 


Comments: 
None 


See Also: 
IDOWNLOAD SetHeaders() 
Return to the List of functions 
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IDOWNLOAD Getlteminfo() 


Description: 


This is the post-1.01 mechanism that allows the caller to query information about the 
item associated the specified item ID. The download engine will either retrieve cached 
information regarding the item or request the information from the server. 


This call is passed a user callback. This callback will be called when the information for 
the associated item has been retreived. 


Unlike a callto DOWNLOAD Enum, this call will retrieve information ONLY about the 
specified item. It will not enumerate the contents of an item of type DLI CATEGORY. 


A call to this mechanism cancels any other pending calls. 


NOTE: Caching of information is provided inside the protocol. There is no need to 
cache information. Information will not be retrieved from the network unless the cache 
is invalid. 


Prototype: 


void IDOWNLOAD GetItemInfo 
( 
IDownload * po, 
DLITEMID id, 
PENDLENUM pÊfn, 
void * pcxt 


) 








Parameters: 
po [in] Pointer to the [Download interface object. 
id [in] Item ID for the operation. 
pfn [in] User callback to be called for each item retrieved. 
pext [in] User context handle passed as first parameter to callback. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetltemList() 


Description: 
** Version 1.0 Legacy Function - Use IDOWNLOAD Enum() instead * * 


Asynchronously retrieves the list of applications for the specified category ID. Note that 
if the specified id is O, all known applications will be retrieved. 


Prototype: 


void IDOWNLOAD GetItemList 
( 
IDownload * po, 
DLCATID id, 
DLItemType t, 
PENDLITEMLIST pÊfn, 
void * pcxt 


) 











Parameters: 
po Pointer to the IDownload interface object. 
id Category ID (0 - all) 
t Type of item to download (0 - all) 
pfn Pointer to callback function. 
pctxt Pointer to user data context passed as first argument to function 


Return Value: 
Upon completion the callback is called with the appropriate error value. 
If the error code is O (success), the item list pointer provided is valid. 


Comments: 
None 


Side Effects: 


This call will attempt to initiate a network connection. 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetModlnfo() 


Description: 


This function allocates and returns a structure containing information regarding 
applications associated with a particular DLITEMID. 





Prototype: 

AppModInfo * IDOWNNLOAD GeModInfo (IDownload * po, DLITEMID appID) 
Parameters: 

po [in] Pointer to the IDownload interface object. 


appiD [in] Application ID (returned from IDOWNLOAD GetAppIDList()). 


Return Value: 


SUCCESS: Returns a pointer to the AppModlnfo. This pointer is valid until a 
subsequent call is made to DOWNLOAD GetModlnfo or the interface is released. 


FAILURE: NULL. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetSize() 


Description: 
This function returns the total size required to download any missing portions of the 
specified item. If non-NULL, the pdwTotal is filled with the total size of all files for the 
item. 


Prototype: 


uint32 IDOWNLOAD GetSize 
( 
IDownload * po, 
DLITEMID iID, 
uint32 * pdwTotal 
) 





Parameters: 
po [in] Pointer to the IDownload interface object. 
ID [in] Item ID. 
pdwTotal [out] Total bytes of all files (resident and non-resident). 


Return Value: 
Size of non-resident file(s) to be downloaded. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD GetSizeEx() 


Description: 


This method calculates the size required to store an item of 1-N packages. It returns 
an error if the size required is unavailable on the device. 


Prototype: 


int IDOWNLOAD GetSizeEx 
( 
IDownload * po, 
DLITEMID iID, 
DLItemSize * psi 
); 








Parameters: 
po [in] Pointer to the IDownload interface object. 
ID [in] Item ID to check 
psi [out] Size information 


Return Value: 
SUCCESS - If the size is obtained 
EFSFULL - Insufficient FS storage space (dwFSAvail < dwFSRequired) 


ENOMEMORY - Insufficient contiguous RAM for the item (dwRAM < 
dwEstRAMReqguired) 


EOUTOFNODES - Insufficient file handles available (nFilesAvail < nEstFileRequired) 
EBADPARM - If psi is NULL or the package is invalid 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD Lock() 


Description: 


This function is used to either lock or unlock a module. Locking a module prevents it 
from being auto-disabled. 





Prototype: 

boolean IDOWNLOAD Lock (IDownload * po, DLITEMID id, boolean bLock); 
Parameters: 

po [in] Pointer to the IDownload interface object. 

id [in] Item ID for the operation. 

bLock [in] TRUE if needs to be locked, FALSE otherwise 


Return Value: 
TRUE - Module locked or unlocked 
FALSE - Lock or unlock failed 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD LogEnuminit() 


Description: 
Initializes the enumeration of download log entries. 





Prototype: 

int IDOWNLOAD LogEnumInit (IDownload * po) 
Parameters: 

po [in] Pointer to the [Download interface object. 


Return Value: 
SUCCESS - Successfully initialized 
EFAILED - Log file does not exist. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD LogEnumNext() 





Description: 
Returns the next available log entry. Returns FALSE if there are no more log items to 
enumerate. 
Prototype: 
boolean IDOWNLOAD LogEnumNext (IDownload * po, DLLogIltem * pli) 
Parameters: 
po [in] Pointer to the IDownload interface object. 
pli [in/out] Pointer to log item entry to fill. 


Return Value: 
TRUE - success 
FALSE - no more items 


Comments: 
None 


See Also: 
None 
Return to the List of functions 


258 


Era [Download Interface 


IDOWNLOAD OnsStatus() 


Description: 
This function is passed a function callback that is called when any activity occurs as a 
result of calls to the [Download class. This includes status regarding recalled 
applications, download status, etc. 


Prototype: 

void IDOWNLOAD OnStatus (IDownload * po, PENDLSTATUS pfn, void * pUser) 
Parameters: 

po [in] Pointer to the IDownload interface object. 

pfn [in] Pointer to status callback function. 

pUser [in] Pointer to user data context passed as first argument to function. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD Restore() 


Description: 
Asynchronously restores an applet that has been removed to save memory. The 
application is downloaded free of charge and no billing transaction is generated. 


Prototype: 
void IDOWNLOAD Restore 
( 
IDownload * po, 
DLITEMID id, 
PENDLCOMMAND pfn, 
void * pcxt 


) 





Parameters: 
po [in] Pointer to the [Download interface object. 
id [in] Application ID. 


Return Value: 
Upon completion, the callback specified is called with the associated completion 
code/error value. A code of O indicates success. 


Comments: 
None 


Side Effects: 


This call will attempt to initiate a network connection. 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD Search() 


Description: 


This is the post-1.01 function initiates a search of ADS items that fulfill the search 
criteria specified. The retum value works identically to the DOWNLOAD Enum() 
function. 


Prototype: 


void IDOWNLOAD Search 
( 
IDownload * po, 
const AECHAR * psgz, 
DLSearchType st, 
PENDLENUM pÊfn, 
void * pcxt 


) 








Parameters: 
po [in] Pointer to the IDownload interface object. 
psz [in] Search string. The string specified is a comma separated list of 
keywords, 
st [in] Search type (ANY, ALL). 
pfn [in] Search callback. 
pcxt [in] User context. 


Return Value: 
None 


Comments: 
None 


See Also: 
IDOWNLOAD Enum() 
Return to the List of functions 
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IDOWNLOAD SetADS() 


Description: 


This function allows the caller to set the server that the download mechanism will use. 
Itis provided ONLY for debug purposes and is NOT supported on production handsets. 


Prototype: 

boolean IDOWNLOAD SetADS (IDownload * po, ADSInfo * ps) 
Parameters: 

po [in] Pointer to the [Download interface object. 

ps [in] Pointer to structure containing server information. 


Return Value: 
TRUE - success 
FALSE - function not supported 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IDOWNLOAD SetHeaders() 


Description: 


This is the post-1.01 function allows the application to specify a special HTTP headers 
that will be sent to the ADS on all requests. The format is as follows: 


"Name: ValrinName:ValrinName: Vahan" 
Passing a NULL value for the header removes the extra headers. 


Prototype: 

void IDOWNLOAD SetHeaders (IDownload * po, const char * pszHeader) 
Parameters: 

po [in] Pointer to the IDownload interface object. 


pszHeaders [in] Pointer to HTTP headers. 


Return Value: 
None 


Comments: 
None 


See Also: 
IDOWNLOAD GetHeaders() 
Return to the List of functions 
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IDOWNLOAD SetSubscriberlD() 


Description: 


This function allows the caller to set the subscriber ID. 


Prototype: 


void IDOWNLOAD SetSubscriberID 


( 


IDownload * po, 
const char * pszSID, 


int nSize 


) 


Parameters: 
po [in] 
pszSID [in] 
nSize [in] 


Return Value: 
None 


Comments: 
None 


See Also: 
None 


Pointer to the [Download interface object. 
Pointer to SID. 


Size in bytes of subscriber ID (if <= O assumed to be 
DEFAULT SUBSCRIBERID LEN). 


Return to the List of functions 
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This interface provides functions for drawing and measuring text. Applications will not typically 
call IFont member functions directly. IDisplay provides a friendlier and more convenient 
interface to drawing text, with support for system colors and clipping state, as well as many 
features related to drawing text, such as underlining, centering, framing, and erasing 
backgrounds. IFont's functions are stricter about arguments and less flexible in defaulting 
values. As IDisplay builds on IFont and any IFont can be passed to IDisplay for it to manage, 
using IFont directly offers no increase in functionality. 


IFont is an interface with multiple implementations. Some IFont classes might work only with 
a particular class of IBitmap, whereas others will work with any IBitmap that supports 1-bit blits. 
By default, IDisplay uses IFont objects provided by the OEM. These can differ in size and 
appearance from handset to handset, and some may not support off-screen bitmaps. 


List of Header files to be included 

The following header file is required: 
AEEFont.h 

List of functions 


Functions in this interface include: 


IFONT AddRef() 

IFONT DrawText() 
IFONT Getinfo() 

IFONT MeasureText() 
IFONT Querylnterface() 
IFONT Release() 


The remainder of this section provides details for each function. 
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IFONT AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IFONT Release() 
Return to the List of functions 
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IFONT DrawText() 


Description: 


IFont Interface 


This function draws text into a bitmap. The x and y parameters describe the placement 
of the top-left corner of the left most character cell. 


The drawing operation is limited to the rectangle *prcClip. Any portions of the text that 
fall outside of this rectangle (or outside the bounds of the bitmap) will not be drawn. 
Clipping affects whether or not pixels are drawn; clipping never affects where things 
are drawn. 


All parameters to IFONT. DrawText() should be valid. Invalid or special values are not 
interpreted to have special meanings, as in IDisplay. The dwFlag parameter consists 
of a set of bit flags that select certain options. The values are defined as for 
IDISPLAY DrawText(), but only IDF TEXT TRANSPARENT is supported. When 
IDF TEXT TRANSPARENT is specified, only the foreground portion (i.e. the 
graphical representation the character) is drawn over any pixels previously occupying 
the destination rectangle. Otherwise, each character cell is drawn in its entirety (both 
foreground and background pixels). 


Prototype: 


int IFONT DrawText 
( 
IFont *pIFont, 
IBitmap *pDst, 
int x, 
int y, 
const AECHAR *pcText, 
int nChars, 
NativeColor foreground, 
NativeColor background, 
const AEERect *prcClip, 
uint32 dwFlags 
) 























Parameters: 


plFont [in] Pointer to the IFont Interface. 

pDst [inllout] Pointer to the destination IBitmap 

x [in] X coordinate of the text string. 

y [in] Y coordinate of the text string. 

pcText [in] Text string to be drawn. 

nChars [in] Text string length. If this is -1, then the length is automatically 


computed by this function 

Color to draw text. 

Color to draw background. 

Clipping rectangle in which the text string must be drawn. 
Properties bitmap that dictates the appearance of the text 
display. 


foreground [in] 
background | [in] 
preClip [in] 
dwFlags [in] 
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Return Value: 
SUCCESS, if successful. 
Error code, if otherwise 


EUNSUPPORTED, if the underlying IBitmap does not support operations required 
by the font. 


Other implementation-specific error codes 


Comments: 


Negative x and y values are legal and indicate a starting position to the left of or above 
the top of the bitmap. In such cases, any portion of the text that extends into the bitmap 
(and into *prcClip) is drawn. 


When the width or height of *prcClip is negative, nothing is drawn. 


The foreground and background color values are NativeColor values and not RGBVAL 
values. 


These can be obtained by calling the destination bitmap's IBITMAP RGBToNative() 
member function. 


See Also: 
NativeColor 
IBITMAP RGBToNative() 
IFONT MeasureText() 
Return to the List of functions 


268 


Erevi IFont Interface 


IFONT Getlnfo() 


Description: 
This function fills the AEEFontlnfo structure with information about the font. The ascent 
and descent values are returned. 
The size of the structure is passed for backward compatibility. The implementation 


should only fill the structure up to the specified size. If the size is larger that than the 
sizeof(AEEFontinfo), this function should return EUNSUPPORTED. 














Prototype: 

int IFONT GetInfo(IFont * pIFont, AEEFontInfo * pinfo, int nSize) 
Parameters: 

plFont [in] Pointer to the IFont Interface. 

pinfo [out] Pointer to the AEEFontinfo structure to fill. 

nSize [in] Size of structure to fill. 


Return Value: 
SUCCESS, if font info is retrieved. 
EUNSUPPORTED, if the version determined by the nSize is not supported. 


Comments: 


IFONT Getlnfo() should always succeed when a valid pinfo pointer is passed and 
nSize is equal to sizeof(AEEFontinfo). 


See Also: 
AEEFontinfo 
IFONT MeasureText() 
Return to the List of functions 
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IFont Interface 


IFONT MeasureText() 


Description: 


This function measures the width of text. It calculates the number of characters that fit 
in the given maximum width as well as the number of pixels that those characters take 
up. All parameters to IFONT MeasureText() must be valid. Invalid or special values are 
not interpreted to have special meanings. 


Prototype: 


int IFONT MeasureText 


( 


IFont *pIFont, 
const AECHAR *pcText, 


int 
int 
int 
int 


) 


Parameters: 


plFont 
pcText 
nChars 


nMaxWidth 
pnFits 


pnPixels 


Return Value: 





nChars, 
nMaxWidth, 
*pnFits, 
*pnPixels 


[in] Pointer to the IFont Interface. 

[in] Text string to be measured in pixels. 

[in] The number of AECHAR characters to measure. Zero (0) 
indicated an empty string (width O (zero)) 
Negative values may not be specified. 

[in] Maximum available screen width in pixels. 

[out] Number of characters that can fit in the screen of the given 
available width. 

[out] Total width of the text string in pixels that can fitin the available 
space. 


SUCCESS, if successful 


Error Code, 


Comments: 
None 


See Also: 


if unsuccessful 


IFONT Getinfo() 
Return to the List of functions 
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IFONT Querylnterface() 


Description: 


This function retrieves a pointer to an interface conforming to the definition of the 
specified class ID. This can be used to query for extended functionality, like future 
versions or proprietary extensions. 


Upon a successful query, an instance of the interface is returned. The caller is 
responsible for calling Release() at some point in the future. One exception is when the 
pointer returned is not an interface pointer. In that case, the memory will share the 
lifetime of the object being queried, and the retumed pointer will not be used to free or 
release the object. 


Prototype: 
int IFONT QueryInterface(IFont * pIFont, AEECLSID id, void ** p) 
Parameters: 
plFont [in] Pointer to the IFont Interface. 
id [in] A globally unique ID to identify the entity (interface or data) that is 
to be queried. 
p [out] Pointer to the data or interface that is to be retrieved. If the value 
passed back is NULL, the interface or data being queried is not 
available. 


Return Value: 
SUCCESS, on success, 
ECLASSNOTSUPPORT, if class ID not supported 


Comments: 
On failure, QuerylInterface() must set *p to NULL. 


See Also: 
None 
Return to the List of functions 
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IFONT Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IFONT AddRef() 
Return to the List of functions 
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IGSM1xControl Interface 


IGSM1xControl interface enables GSM1x capability on the mobile. It contains interfaces that 
are the building blocks for GSM1x Activation BREW Applet. 


The interfaces support provisioning of GSM1x data from SIM or R-UIM to a specially 
designated NAM in NV as well as switching between NAMS at run time. 


Typically, GSM1x Activation BREW Applet will follow the following sequence of operations: 


* Find out the current mode using IGSM1xControl GetCurrentMode(). 
* Find out which modes are available using IGSM1xControl GetAvailableModes(). 


* lfno provisioning modes are available, go to "Emergency calls only" state using 
IGSM1xControl ActivateNonGSM1xMode() and exit. 


* Choose the new provisioning mode either automatically or by interacting with the 
user. 


* lfthe new mode is CDMA1x, select it using 
IGSM1xControl ActivateNonGSM1xMode(). 


* lfthe new mode is GSM1x, do the following sequence (order is important) of 
operations: 


— Call IGSM1xControl ProvisionGSM1xParameters() to provision IMSI, 
ACCOLC and MSISDN. 


Form GSM1x PRL and set it using IGSM1xControl Set6GSM1xPRL(). 


Set home and locked SID/NID pairs using 
IGSM1xControl SetGSM1xSIDNIDPairs() 


Call ISSM1xControl EnableGSM1xMode(). 


GSM1x Activation BREW Applet can, optionally, provide interactive editing capability for 
PLMN selector and forbidden PLMN information stored in SIM/R-UIM. 
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In addition to its core functionality, this class is used to signal GSM1x BREW Applets (other 
than GSM1x Activation BREW Applet) whenever GSM1x mode is activated or de-activated. 
ISSM1xControl sends event notification whenever GSM1x mode changes (enabled or 
disabled). Whenever a new mode is activated on IGSM1xControl it sends out a 

NMASK GSM1xCONTROL STATUS CHANGE notification. AEEGSM1xControl statusType 
is sent as dwParam member of the EVT NOTIFY event. 


To send out notification, a helper class IGSM1xControlNotifier is used. Methods for 
IGSM1xControlNotifier should not be called directly by BREW applets. Brew applet should 
specify the class id for ISSM1xControlNotifier and the 

NMASK=NMASK GSM1xCONTROL STATUS CHANGE in its MIF file. 


In general, all GSM1x applets should behave as follows: 


On Init 
* Register to receive NMASK GSM1xCONTROL STATUS CHANGE. 


* Call IGSM1xSig GetStatus()to ensure that GSM1x capability is enabled. 
If GSM1x capability is disabled, application can exit with an appropriate message or 
wait until it receives a GSM1xSIG STATUS CHANGE event with 
GSM1xSIG ACTIVE. 
Runtime 
* lfa GSM1xSIG STATUS CHANGE event is received, handle it appropriately. 
The IGSM1xControl interface is obtained via the ISHELL Createlnstance() mechanism. 
List of Header files to be included 


The following header file is required: 


AEEGSM1xControl.h 
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List of functions 


Functions in this interface include: 


IGSSM1xControl ActivateNonGSM1xMode() 
IGSSM1xControl Enable6SM1xMode() 
IGSSM1xControl GetAvailableModes() 
IGSSM1xControl GetCurrentMode() 
IGSM1xControl GetDFPresence() 
IGSM1xControl GetGSM1xPRL() 
ISSM1xControl Get6GSM1xSIDNIDPairs() 
IGSSM1xControl GetPLMN() 

IGSM1xControl GetSupportedProvisioningModes() 
IGSSM1xControl GetUIMUniqueld() 
IGSM1xControl ProvisionGSM1xParameters() 
IGSM1xControl Set6GSM1xPRL() 
IGSM1xControl Set6GSM1xSIDNIDPairs() 
IGSM1xControl SetPLMN() 

IGSM1xControl ValidatePRL() 


The remainder of this section provides details for each function. 


See Also: 
IGSM1xSig Interface 
IQuerylInterface 
Return to the IGSM1xControl Interface 
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IGSM1xControl ActivateNon6GSM1xMode() 


This function 
This function activates the specified provisioning mode: 
AEEGSMIXCONTROL 1X NV PROV MASK 
AEEGSMIXCONTROL 1X RUIM PROV MASK 
AEEGSMIXCONTROL EMERGENCY PROV MASK 


Prototype: 


AEEGSMixControl statusType IGSMixControl ActivateNonGSMixMode 
( 
IGSMixControl *instancePtr, 
AEEGSMixControl DFPresenceBitMaskType mode 
) 


























Parameters: 


instancePtr Pointer to the IGSM1xControl Interface object. 
mode The desired provisioning mode. 


Return Value: 
AEEGSM1xControl statusType 


Comments: 


This function is usually called by the GSM1x Activation App when a user desires to 
switch to CDMA 1x provisioning mode.. 


Side Effects: 
NMASK GSM1xSIG STATUS CHANGE notification sent to all registered apps. 


See Also: 
None 
Return to the List of functions 
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IGSM1xControl EnableGSM1xMode() 


This function 


This routine commands DMSS's Call Manager module to switch to the GSM1x NAM. 
Call Manager will take the phone offline and then re-do the system determination. 


Prototype: 


AEEGSMixControl statusType IGSMlxControl EnableGSMixMode 
( 

IGSMixControl *instancePtr 

) 














Parameters: 
instancePtr Pointer to the IGSM1xControl object. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 


This routine is synchronious - it waits till the phone finishes system determination (that 
can take significant amount of time.) This function is usually called by the GSM1x 
Activation App as the final step in activating GSM1x mode. 


Side Effects: 


NMASK GSM1xCONTROL STATUS CHANGE notification is sent to all registered 
applications. 


See Also: 
None 
Return to the List of functions 
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IGSM1xControl GetAvailableModes() 


Description: 


This function returns (as a bit mask) which of the provisioning modes are currently 
available for selection. This is determined by the software build and by the presence 
and the type of the User Identity Module. 


Prototype: 


AEEGSMixControl statusType IGSMixControl GetAvailableModes 
( 
IGSMixControl *instancePtr, 

AEEGSMixControl modeBitMaskType *modeMask 

) 























Parameters: 


instancePtr Pointer to the IGSM1xControl object. 


modeMask | Pointer to a memory location to receive the bitmask which indicates the 
supported modes. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSM1xControl GetCurrentMode() 


Description: 
This function retrieves the current provisioning mode. 


Prototype: 


AEEGSMixControl statusType IGSMixControl GetCurrentMode 
( 
IGSMixControl *instancePtr, 

AEEGSMixControl modeBitMaskType *modeMask 

) 


























Parameters: 


instancePtr Pointer to the IGSM1xControl object. 
modeMask | Pointer to a memory location to receive the current provisioning mode. 


Return Value: 


AEEGSM1xControl statusType- the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
Can be used by the GSM1x Activation App to display the current provisioning mode. 


See Also: 
None 
Return to the List of functions 
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IGSM1xControl GetDFPresence() 


Description: 


This function returns the indication which directory files (DFs) are present on the 
currently available user identity card (SIM or R-UIM.) 


Prototype: 


AEEGSMixControl statusType IGSMixControl GetDFPresence 
( 
IGSMixControl *instancePtr, 
AEEGSMixControl DFPresenceBitMaskType *presenceMask 
) 


























Parameters: 


instancePtr Pointer to the IGSM1xControl object. 


presenceMask Pointer to a memory location to receive the bitmask that indicates 
which DFs are present. 


Currently, the following DFs are supported: 
AEEGSMIXCONTROL MF PRESENT 
AEEGSMIXCONTROL CDMA DF PRESENT 
AEEGSMIXCONTROL GSM DF PRESENT 

To be supported in a future release: 
AEEGSMIXCONTROL DCS1800 DF PRESENT 


The contents of this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 


AEEGSMIXCONTROL DCS1800 DF PRESENT is currently not supported, its 
mask will not be returned by this call. 


See Also: 
None 
Return to the List of functions 
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IGSM1xControl Get6GSM1xPRL() 


Description: 
This function returns the packed PRL stored in the NAM assigned to GSM1x. Format 
of the PRL depends on the software build IS683A or IS683C). 


Prototype: 
AEEGSMIxControl statusType IGSMixControl GetGSMIxPRL 
( 
IGSMixControl *pIGSMixControl, 
uintl6 maxPRLSizeBytes, 
byte *packedPRL, 
) 











Parameters: 
pIGsMixControl Pointer to the IGSM1xControl object. 
maxPRLSizeBytes specifies the maximum size of the buffer pointed by packedPRL. 
packedPRL Pointer to a memory location to receive the PRL. The contents of 


this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


Return Value: 


AEEGSM1xControl statusType - the set of returned valuesare defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
IGSM1xControl Set6GSM1xPRL() 
Return to the List of functions 
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IGSM1xControl GetGSM1xSIDNIDPairs() 


Description: 
This function retrieve Home and Locked SID/NID pairs stored in NV. 


Prototype: 


AEEGSMixControl statusType IGSMixControl GetGSMlixSIDNIDPairs 

( 

IGSMixControl *pInstance, 

uint16 HomeSIDNIDMaxCnt, 
AEEGSMixControl SIDNIDPairType *HomeSIDNIDPairs, 
uint16 *ActualHomeSIDNIDCnt, 
uint1l6 LockedSIDNIDMaxCnt, 
AEEGSMixControl SIDNIDPairType *LockedSIDNIDPairs, 
uintl6 *ActualLockedSIDNIDCnt 
) 









































Parameters: 
pInstance Pointer to the IGSM1xControl object. 
HomeSIDNIDMaxCnt Maximum number of SID/NID pairs that can be stored in 
the memory location pointed by HomeSIDNIDPairs. 
HomeSIDNIDPairs Pointer to a memory location to receive Home SID/NID 


pairs. The contents of this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


ActualHomeSIDNIDCnt Pointer to a memory location to receive the actual count of 
Home SID/NID pairs written to HomeSIDNIDPairs. The 
contents of this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


LockedSIDNIDMaxCnt Maximum number of SID/NID pairs that can be stored in 
the memory location pointed by LockedSIDNIDPairs. 


LockedSIDNIDPairs Pointer to a memory location to receive Locked SID/NID 
pairs. The contents of this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


ActuallLockedSIDNIDCnt Pointer toa memory location to receive the actual count of 
Home SID/NID pairs written to LockedSIDNIDPairs. The 
contents of this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 
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See Also: 


IGSM1xControl Set6GSM1xSIDNIDPairs() 
Return to the List of functions 
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IGSM1xControl GetPLMN() 


Description: 


This function reads from a SIM or R-UIM card and returns the PLMN entries for all 
types specified by the provided bitmask. 


A Home PLMN is retrieved from the EFimsi counting the EFad. 
A PLMN Selector is retrieved from the EFpImnsel. 
A Forbidden PLMN is retrieved from the EFfpImn. 


Prototype: 


AEEGSMIxControl statusType IGSMixControl Get PLMN 

( 

IGSMixControl *instancePtr, 
AEEGSMixControl PILMNTypeBitMaskType types, 
uint16 maxPLMNEntriesCnt, 
AEEGSMixControl PILMNTripletType *PLMNBuf, 
uint1l6 *actualPLMNEntriesCnt 
) 


















































Parameters: 


instancePtr Pointer to the IGSM1xControl object. types specifies a 
bitmask that specifies which types of PLMN information are 
requested 

AEEGSMIXCONTROL HOME PLMN 
AEEGSMIXCONTROL SEL PLMN 
AEEGSMIXCONTROL FORBIDDEN PLMN ). 
maxPLMNEntriesCnt Maximum number of PLMN entries that can fit into the 
location pointed by PLMNBuf. 

PLMNBuf Pointer to a memory location to receive the array of PLMN 
elements. The contents of this location are undefined unless 
AEEGSM1XCONTROL STATUS SUCCESS is returned. 

actualPLMNEntriesCnt Pointer to a memory location to receive the actual number 
of entries copied into the location pointed by PLMNBuf. The 
contents of the location pointed by actualPLMNEntriesCnt 
are undefined unless 
AEEGSM1XCONTROL STATUS SUCCESS is returned. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 


None 
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See Also: 


IGSM1xControl SetPLMN() 
Return to the List of functions 
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IGSM1xControl GetSupportedProvisioningModes() 


Description: 


This function returns the bit mask that indicates which of the possible provisioning 
modes are supported by the software (OEM). Note, that this calls does not take into 
account the presence and the type of a User Identity Module (smartcard.) Thus, even 
if some mode are supported by the software, user might not be able to use them 
because the user does not have a "right" UIM. 


Prototype: 
AEEGSMixControl statusType 
IGSMixControl GetSupportedProvisioningModes 
( 
IGSMixControl *instancePtr, 
ABEEGSMixControl DFPresenceBitMaskType *modeMask 
) 























Parameters: 


instancePtr Pointer to the IGSM1xControl object. 

modeMask | Bit mask that contains zero or more values 
AEEGSMIXCONTROL GSM1X PROV MASK, 
AEEGSMIXCONTROL 1X NV PROV MASK, 
AEEGSMIXCONTROL 1X RUIM PROV MASK. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix 


AEEGSMIXCONTROL STATUS . 


Comments: 
Relies on the implementation provided by OEMs. 


See Also: 
None 
Return to the List of functions 


286 


brew. 


IGSM1xControl Interface 


IGSM1xControl GetUlIMUniqueld() 


Description: 


This function returns the unique ICCld stored in EFiccid field on SIM or R-UIM. The 
normal length is 10 bytes. 


Prototype: 











( 


AEEGSMixControl statusType IGSMlixControl GetUIMUniqueId 


IGSMixControl *pInstance, 
uint16 maxBufLen, 

byte *pId, 

uint1l6 *actualLen 


) 


Parameters: 


instancePtr 
maxBufLen 
pld 


actualLen 


Return Value: 


Pointer to the IGSM1xControl object. 

Maximum length of a memory buffer pointed by pld. 

Pointer to a memory location to receive the ICCld. The contents of this 
location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. This location 
should have at least 10 bytes available. 

Pointer to a memory location to receive the actual length of ICCld. The 
contents of this location are undefined unless 
AEEGSMIXCONTROL STATUS SUCCESS is returned. 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None. 


See Also: 
None. 


Return to the List of functions 
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IGSM1xControl ProvisionGSM1xParameters() 


Description: 
This routine reads GSM IMSI, ACCOLC, and MSISDN from the present UIM card if 
any), converts it to CDMA IMSI, ACCOLC and MSISDN according to GSM1x 
provisioning algorithm, and writes the results into in NV, associated with GSM1x NAM. 


Prototype: 
AEEGSMixControl statusType IGSMixControl ProvisionGSMlixParameters 


( 
IGSMixControl *instancePtr 


) 











Parameters: 
instancePtr Pointer to the IGSM1xControl object. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSM1xControl SetGSM1xPRL() 


Description: 
Description: 


This function validates supplied packed PRL and (if valid) writes it to the GSM1x NAM 
in NV. 


The supplied PRL must have the following format: 
reserved (1 byte) will be filled by this function 
prl version (2 bytes) 
size (2 bytes) PRL size in bits 
valid (1 byte) boolean 
roaming list(variable length) packed I5683A format 


Prototype: 
AEEGSMlxControl statusType IGSMIixControl SetGSMixPRL 
( 
IGSMixControl *instancePtr, 
byte *packedPRL 
) 














Parameters: 
instancePtr Pointer to the IGSM1xControl object. 
packedPRL Pointer to a memory location that contains PRL to be written. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
IGSM1xControl GetGSM1xPRL() 
Return to the List of functions 


289 


Eri IGSM1xControl Interface 


IGSM1xControl Set6GSM1xSIDNIDPairs() 


Description: 
This function sets the specified Home and Locked SID/NID pairs in NV. 


Prototype: 
AEEGSMixControl statusType IGSMixControl SetGSMlIxSIDNIDPairs 
( 
IGSMlixControl *pInstance, 
uint16 HomeSIDNIDCnt, 
AEEGSMixControl SIDNIDPairType *HomeSIDNIDPairs, 
uint16 LockedSIDNIDCnt, 
AEEGSMixControl SIDNIDPairType *LockedSIDNIDPairs 
) 






































Parameters: 


instancePtr Pointer to the IGSM1xControl object. 

HomeSIDNIDCnt Number of SID/NID pairs located in the buffer pointed by 
HomeSIDNIDPairs. 

HomeSIDNIDPairs Pointer to a memory location that contains home SID/NID 
pairs. 

LockedSIDNIDCnt | Number of SID/NID pairs located in the buffer pointed by 
LockedSIDNIDPairs. 


LockedSIDNIDPairs Pointer to a memory location that contains locked SID/NID 
pairs. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
IGSM1xControl Get6GSM1xSIDNIDPairs() 
Return to the List of functions 
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IGSM1xControl SetPLMN() 


Description: 
This function writes the supplied PLMN information to EFpImnsel and/or EFfpImn fields 
in DFgsm on the currently available SIM or R-UIM card. 
The entries having type AEEGSMIXCONTROL HOME PLMN are ignored. 
The entries having type AEEGSMIXCONTROL SEL PLMN are written to 
EFpImnsel in the same order as they are present in the supplied array. 
If there are more entries specified than can fitinto EFpImnsel field,the extra entries are 
ignored. The entries having typeAEEGSM1XCONTROL FORBIDDEN PLMN are 
written to EFfpImn fieldin the same order as they are present in the supplied array.If 
there are more entries specified than can fit into EFfpImn field,the extra entries are 
ignored. 


Prototype: 

AEEGSMixControl statusType IGSMixControl Set PLMN 
( 
IGSMixControl *instancePtr, 
uint16 PLMNEntriesCnt, 

AEEGSMixControl PLMNTripletType *PLMNBuf 

) 





























Parameters: 
instancePtr Pointer to the IGSM1xControl object. 
PLMNEntriesCnt Number of entries in the supplied array. 
PLMNBuf Pointer to the array containing the PLMN entries to be written. 


Return Value: 
AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
IGSM1xControl GetPLMN( 


Return to the List of functions 
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IGSM1xControl ValidatePRL() 


Description: 
This function validates the supplied packed PRL. In order to validate, the supplied PRL 
must have the same format |S683A or |15683C) as the phone software. The PRL format 
does not allow specification of the standard used. 


Prototype: 
AEEGSMixControl statusType IGSMlixControl ValidatePRL 
( 
IGSMixControl *pInstance, 
byte *packedPRL, 
boolean *isValid 


) 











Parameters: 
pInstance Pointer to the IGSM1xControl object. 
packedPRL Pointer to a memory location that contains PRL to be validated. 
isValid Pointer to a memory location to receive the information whether the 


supplied PRL is valid or not. The contents of this location are 
undefined unless AEEGSM1XCONTROL STATUS SUCCESS is 
retumed. 


Return Value: 


AEEGSM1xControl statusType - the set of returned values are defined by constants 
whose name starts with the prefix AEEGSM1XCONTROL STATUS . 


Comments: 
None 


See Also: 
IGSM1xControl Set6GSM1xPRL() 
Return to the List of functions 
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IGSM1xSig Interface 


Description: 
IGSM1xSig interface enables GSM1x capability on the mobile device. It provides an 
interface to the GSM1x Signaling layer. It also provides a method to check the status 
of the GSM1x capability. 
It provides the following services: 
Sending GSM1x Signaling Msg to network 
Notification upon receiving GSM1x Signaling Msg from Network 
Checking the status of GSM1x. 
The IGSM1xSig interface is obtained via the ISHELL Createlnstance mechanism. 
To send event notifications, IGSM1xSig uses a helper class IGSM1xSigNotifier. 
Methods for IGSM1xSigNotifier should not be called directly by BREW applets. Brew 
applet should specify the class id for ISSM1xSigNotifier and the NMASK in its MIF file. 
Only one type of event notification is provided: 
NMASK GSM1xSIG PROTOCOL TYPE 
This event is send whenever a GSM1x signaling message is received. While 
registering applet should specify the value indicating the protocol type applet is 
interested in. An applet will only receive signaling messages for the protocol types 
ithas registered for. 


A pointer to AEEGSM1xSig SignalingMessageType struct is sent as dwParam 
member ofthe EVT NOTIFY event. 


In general if an applet is interested in messages for protocol type “x”, it should 
specify a NMASK of (NMASK GSM1xSIG PROTOCOL TYPE | x). 


Possible values for protocol type are specified in enum type 
AEEGSM1xSig ProtocolTypes. 
List of Header files to be included 


The following header file is required: 


AEEGSM1xSig.h 
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List of functions 
Functions in this interface include: 


IGSM1xSig GetStatus() 
IGSM1xSig SendSignalingMessage() 
IGSSM1xSig SendSignalingReject() 


The remainder of this section provides details for each function. 
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IGSM1xSig GetStatus() 


Description: 
This method is used to retrieve the current GSM1x status on the phone. This method 
lets the caller know if GSM1x capability is enabled or disabled on the mobile device. 


Prototype: 


AEEGSMlixSig Status IGSMlxSig GetStatus 
( 

IGSMixSig * po 

) 











Parameters: 
po: Pointer to the IGSM1xSig object 


Return Value: 
GSM1xSIG ACTIVE - GSM1x capability enabled on the mobile device. 
GSM1xSIG INACTIVE - GSM1x capability disabled on the mobile device. 


Comments: 
None. 


See Also: 
IGSM1xControl Interface 
Return to the List of functions 
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IGSM1xSig SendSignalingMessage() 


Description: 


This method is used to send a GSM1x signaling message (except for GSM1x 
Authentication Reg/Rsp Message) to the network. 


Prototype: 


int IGSMixSig SendSignalingMessage 
( 
IGSMixSig *po, 

AEEGSMixSig SignalingMessageType *pMsg 
) 

















Parameters: 
po: Pointer to the IGSM1xSig object 


pMsg: Pointer to the AEEGSM1xSig SignalingMessageType struct containing the 
GSM1x signaling msg details 


Return Value: 
SUCCESS - GSM1x Signaling Message queued up. 
EBADPARM - Value in pMsg is invalid (ex. attempting to send Auth msg) 
EFAILED - General Failure in sending out the signaling message 
EITEMBUSY - No more buffers left for sending messages. 
EGSM1x INACTIVE - Phone is not in IGSM1x mode 
EBADCLASS: - IPhone is not initialized. 


Comments: 


This method doesn't guarantee deilvery of the message to the network, it only ensures 
that message was sent from the mobile device. It is up to the calling routines to use 
other mechanism (ex. explicit ack) to detemine if the network entity received the 
message 


See Also: 
AEEGSM1xSig SignalingMessageType 
Return to the List of functions 
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IGSM1xSig SendSignalingReject() 


Description: 
This method is used to send a GSM1x signaling reject message to the network. 


Prototype: 


int IGSMixSig SendSignalingReject 
( 
IGSMixSig *po, 

AEEGSMixSig RejectMessageType *pMsg 
) 














Parameters: 
po: Pointer to the IGSM1xSig object 


pMsg: Pointer to the AEEGSM1xSig RejectMessageType struct containing the 
GSM1x signaling reject msg 


Return Value: 
SUCCESS - GSM1x Reject Message queued up. 
EBADPARM - Value in pMsg is invalid (ex. attempting to send Auth msg) 
EFAILED - General Failure in sending out the signaling message 
EITEMBUSY - No more buffers left for sending messages. 
EGSM1x INACTIVE - Phone is not in IGSM1x mode 
EBADCLASS: - IPhone is not initialized. 


Comments: 
This method doesn't guarantee deilvery of reject messages to the network. 


See Also: 
None 
Return to the List of functions 
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IGSMSMS 


Description: 
ISSMSMS is a simple interface to the GSM1x support layer in the device. 
It provides the following services: 
Sending GSM1x SMS messages (SMS SUBMIT) 
Extracting SMS text and TL data from GSM1x SMS messages 
The IGSMSMS interface is obtained via the ISHELL Createlnstance mechanism. 


List of Header files to be included 


The following header file is required: 


AEEGSMSMS.h 
List of functions 


Functions in this interface include: 


IGSSMSMS CreateDefaultMessage() 
ISSMSMS DecodeMessage() 
ISSMSMS DecodeUserData() 
IGSSMSMS DeleteAllMessages() 
IGSSMSMS DeleteMessage() 

ISSMSMS EncodeUserData() 
ISSMSMS GetMessage() 

ISSMSMS GetMessageStatus() 
ISSMSMS GetMemoryCapExceededFlag() 
IGSMSMS GetSCAddress() 

IGSSMSMS GetStatusReport() 

ISSMSMS GetStoreSize() 

IGSMSMS GetTPMR() 

IGSMSMS Isinit() 

IGSSMSMS MoveMessage() 

ISSMSMS SendMoreMemoryAvailable() 
IGSMSMS SendSMSDeliverReport() 
IGSMSMS SendSMSSubmit() 
IGSMSMS SetSCAddress() 

ISSMSMS SetMemoryCapExceededFlag() 
IGSMSMS SetMessageStatus() 
IGSMSMS SetTPMR() 
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IGSSMSMS StoreMessage() 
IGSMSMS StoreStatusReport() 


The remainder of this section provides details for each function. 
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IGSMSMS CreateDefaultMessage() 


Description: 


This function initializes a Mobile Originated (MO) message structure to the default 
values that are most commontly used. 


The defaults fora GSMSMSSubmitType are: 
SCAddr - Filled in with Default SC Address from SIM 
RD - Reject Duplicates set to True 
VP - Validity Period 
SRR - Status Report Request set to True; 
UDHI - User Data Header Indicator set to False 
RP - Reply Path Parameter is not set (RP=False) 
MR - Message Reference is O and is filled in when sent 
DA - Destination Address is set to "0" and must be 
overwritten by the application 
PID - Protocol ID is SME to SME by default 
DCS - Data coding Scheme is set to GSM-7bit, class None 
UDL - User Data Length is set to O 
UD - User Data is initialized to all zeros 

The defaults fora GSMSMSDeliverReportType: 
SCAddr - Filled in with Default SC Address from SIM 
UDHI - User Data Header Indicator set to False 
FCS present - Failure Cause present is set to False (indicating no failure) 
FCS - Failure Cause is set to O (reserved) 
PID present - Protocol ID is not present (PID present=False) 
PID - Protocol ID is SME to SME by default 
DCS present - Data Coding Scheme is not present (DCS present=False) 
DCS - Data coding Scheme is set to GSM-7bit, class None 
UDL present - User Data Length is not present (DCS present=False) 
UDL - User Data Length is set to O 
UD - User Data is initialized to all zeros 


Prototype: 


int IGSMSMS CreateDefaultMessage 
(IGSMSMS *po, 
GSMSMSMsgType type, 
GSMSMSMsg *pGsmMsg) ; 


Parameters: 
po Pointer to the IGSMSMS object 
type The type of message to create 
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pGsmMsg Pointer to the GSM SMS Msg structure to initialize. 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the the paremeters were not valid: AEE GSMSMS EBADPARAM 
If the message was not valid: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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IGSMSMS DecodeMessage() 


Description: 


This function decodes a raw SMS message into an appropriate structure 
representation. 


The UserData (UD) will not be decoded and can be subsequently: 


AECHAR wszText [GSMSMS MAX UD CHAR]; 
GSMSMSMsg DecodedMsg; 
// Decode Message 
IGSMSMS DecodeMessage (pMe, pNotifyMsg->rawMsg, sizeof (pNotifyMsg- 
>rawMsg), &DecodedMsg) ; 
// Decode UserData 
IGSMSMS DecodeUserData (pMe, DecodedMsg, eawszText [0], 
sizeof (wszText)); 





Prototype: 


int IGSMSMS DecodeMessage 
( 
IGSMSMS * po, 
const GSMSMSRawMsg *pRawMsg, 
const GSMSMSMsg *pMsg 
) 


Parameters: 
po Pointer to the IGSMSMS object 
pRawMsg Pointer to the raw GSM SMS message to decode 
pMsg Pointer to the GSMSMSMsg struct to fill with the decoded information 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the store could not be decoded: AEE GSMSMS EFAILED 
If pRawMsg or pMsg are NULL: AEE GSMSMS EBADPARAM 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS DecodeUserData() 


Description: 


This function is used decode the UserData into UNICODE for display. If the UserData 
contains a user data header it will be skipped. 


ONLY THE RAW TEXT IS RETURNED by this method. If the message is a 
concatinated or EMS message, it must be decoded directly by an external library or by 
the applet. 


See the description ofIGSMSMS DecodeMessage for an example of how this is used. 


If wstrlen is less than the decoded data length, the decoded data will be truncated and 
NULL terminated. 


Prototype: 


IGSMSMS. DecodeUserData 

( 

IGSMSMS * po, 

const GSMSMSMsg *pMsg, 
AECHAR *pwzStr, 
uint16 wstrlen 


) 





Parameters: 
po Pointer to the IGSMSMS object 
pMsg Pointer to the decoded SMS message 
pwzStr Pointer to the unicode string to fill with the decoded data 
wstrlen Size in bytes of the wstr unicode string 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the data could not be decoded: AEE GSMSMS EFAILED 
If PMsg or pwzStr are NULL: AEE GSMSMS EBADPARAM 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS DeleteAllMessages() 


Description: 


This function deletes all entries of a specified type from the store (SIM, NVRAM or 
NVRAM Voivemail). It provides a way to delete only mobile originated (MO), mobile 
terminated (MT), or all messages. 


Prototype: 


int IGSMSMS DeleteAllMessages 
( 
IGSMSMS * po, 
uintl6 msgMask, 
GSMSMSStorageType deleteFrom 
) 


Parameters: 
po Pointer to the IGSMSMS object 
msgMask Indicates the type of messages to delete. Any combination of the 


following 
GSMSMS SIM MO 
GSMSMS SIM MT 
GSMSMS SIM ALL 
deleteFrom Indicates whether to delete from the SIM or from NVRAM database. 


Return Value: 
If successful: AEE GSMSMS SUCCESS. 
If deleteFrom is invalid: AEE GSMSMS EBADPARAM 
If the messages could not be deleted: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS DeleteMessage() 


Description: 
This function deletes an entry from a specified slot on the store (SIM, NVRAM or 
NVRAM Voicemail). 


Prototype: 


void IGSMSMS DeleteMessage 
( 
IGSMSMS * po, 
uint16 index, 
GSMSMSStorageType deleteFrom 
) 


Parameters: 
po Pointer to the IGSMSMS object 
index Slot index of message to delete 


deleteFrom | Indicates whether to delete from the SIM or from NVRAM database. 


Return Value: 
If successful: AEE GSMSMS SUCCESS. 
If deleteFrom is invalid: AEE GSMSMS EBADPARAM 
If the message could not be deleted: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS 


IGSMSMS EncodeUserData() 


Description: 


This function is used to decode the UserData into UNICODE for display. Ifa UserData 
Header is included then address of the offset user data should be passed to this 
function. The udlen parameter must also be reduced accordingly. If the message will 
not fit in the space provided it will be truncated. 


Prototype: 


IGSMSMS | 


( 


EncodeUserData 


IGSMSMS * po, 


co 
by 
by 








nst AECHAR *pwszText, 
te *pDest, 
te destLen, 





GSMEncodingType encoding, 
byte *pEncodedLen 
) 
Parameters: 
po [in] Pointer to the IGSMSMS object 
pwszText [in] Pointer to the unicode string to encode 
pDest [out] Pointer to the part of the UD field to encode the data 
destLen [in] Size in bytes of the UD field left for the encoded string 
encoding [in] Encoding to use for text 
pEncodedLen [out] Length of the encoded text in bytes 


Return Value 


If successful: AEE GSMSMS SUCCESS 


If pUD is NULL, pwszText is NULL or encoding is invalid: 
AEE GSMSMS EBADPARAM 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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IGSMSMS GetMessage() 


Description: 
This function retrieves an SMS entry from a specified slot on the store (SIM or 
NVRAM). The message is retrieved in raw format and can be decoded using 
ISSMSMS DecodeMessage and IGSSMSMS DecodeUserData. 


Prototype: 


int IGSMSMS GetMessage 
( 
IGSMSMS * po, 
uint16 index, 
GSMSMSRawMsg *pMsg, 
GSMSMSStorageType readFrom 
) 


Parameters: 
po Pointer to the IGSMSMS object 
index Slot index of message to retrieve 
pMsg Pointer to struct to be filled in with the retrieved message 
readFrom Indicates whether to read from the SIM or ftfom NVRAM database 


Return Value: 
If successful: AEE GSMSMS SUCCESS. 
If PMsg is NULL, or readFrom is invalid: AEE GSMSMS EBADPARAM 
If the messages could not be read: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS GetMessageStatus() 


Description: 


This function reads the status of a message in the specified store. The status will 
indicate whether the specified slot is free or if the message stored there is mobile 
terminated or mobile originated. Ifthe message is mobile terminated it will also indicate 
whether the message has been read or not. 


lfthe message is mobile originated, it will also indicate whether the message has been 
sent or not and if sent, whether there is a pending or received status report for the 
message. 


Prototype: 


int IGSMSMS GetMesageStatus 
( 
IGSMSMS * po, 
uint16 index, 
GSMSMSStatusType *pStatus, 
GSMSMSStorageType readFrom 
) 


Parameters: 
po Pointer to the IGSMSMS object 
index The index in the store to read from 
pStatus Pointer to the status to read 
readFrom Indicates whether to use the SIM or NVRAM database 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If readFrom is invalid: AEE GSMSMS EBADPARAM 
If the entry could not be updated: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS GetMemoryCapExceededFlag() 


Description: 
This function retrieves the default Memory Capacity Exceeded Flag on the SIM. In 
accordance with the GSM TS 11.11 spec, pFlag is set to O if the flag is set, and set to 
1 ifthe flag is not set. All other values are reserved. 


Prototype: 


void IGSMSMS GetMemoryCapExceededF lag (IGSMSMS * po, uint8 *pFlag) 





Parameters: 
po: Pointer to the IGSSMSMS object 
pFlag: Pointer to variable to set to the value of the flag 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the flag could not be read: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS GetSCAddress() 


Description: 
This function retrieves the default GSM Service Center address from the SIM. 


Prototype: 


int IGSMSMS GetSCAddress 
( 
IGSMSMS * po, 
GSMSMSAddress const *address 
) 


Parameters: 
po Pointer to the IGSMSMS object 
address Pointer to the structure to fill in with the default SC address 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the SC address could not be retrieved: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS GetStatusReport() 


Description: 
This function retrieves an SMS StatusReport entry that corresponds to a SMS Submit 
message in a specified slot on the store (SIM or NVRAM). 


Prototype: 


int IGSMSMS GetStatusReport 
( 
IGSMSMS * po, 
uint16 index, 
GSMSMSRawMsg *pMsg, 
GSMSMSStorageType readFrom 
) 


Parameters: 
po Pointer to the IGSMSMS object 
index Slot index of the SMS Submit corresponds to the status report 
pMsg Pointer to the GSM SMS Msg to write the status report to 
readFrom Indicates whether to read from the SIM or from NVRAM database. 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If readFrom is invalid: AEE GSMSMS EBADPARAM 
If the message could not be read: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS GetStoreSize() 


Description: 
This function returns the size of the store in slots. 


Prototype: 
int AEEGSMSMS GetStoreSize 
( 
IGSMSMS * po, 
GSMSMSStorageType readFrom, 
uint1l6 *pCount 
) 














Parameters: 
po Pointer to the IGSMSMS object 
readFrom Message store to query 
pCount Pointer to the variable to set to the number of slots in the store 


Return Value: 
If successful: AEE GSMSMS SUCCESS 


Otherwise: AEE GSMSMS EBADPARAM 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS GetTPMR() 


Description: 
This function retrieves the last used TP-MR from EF-SMSS on the SIM. 


Prototype: 


int IGSMSMS Get TPMR(IGSMSMS * po, uint8 *pTPMR) 


Parameters: 
po: Pointer to the IGSSMSMS object 
pTPMR: Pointer to variable to set to the value of the TP-MR 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the flag could not be read: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS Islnit() 


Description: 
This function indicates to the user whether the IGSMSMS interface has finished 
internal initialization. If the interface is not initialized, the applet can register for 
NMASK GSMSMS INIT in IGSSMSMS Notifier to be notified when the initialization is 
complete. 


Prototype: 


boolean IGSMSMS IsInit (IGSMSMS *po) 


Parameters: 
po: Pointer to the IGSMSMS object 


Return Value: 
TRUE if initialized, otherwise FALSE 


Comments: 
None 


See Also: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS MoveMessage() 


Description: 


This function moves a GSM SMS message from one store to another. It will also allow 
the the user to move from one slot to another on the same store. 


Prototype: 


int IGSMSMS MoveMessage 
( 
IGSMSMS *po, 
GSMSMSStorageType moveFrom, 
uint16 fromIndex, 
GSMSMSStorageType moveTo, 
uintl6 *pToIndex 
) 





Parameters: 
po Pointer to the IGSMSMS object 
moveFrom | Store to move the message from 
fromindex Index of the message to move 
moveTo Store to move the message to 
pTolndex Pointer to the index of the stored message, if set to 


GSMSMS INDEX ANY an empty slot will be selected and returned 


Return Value: 
AEE GSMSMS SUCCESS, successful. 
AEE GSMSMS ESTORE FULL, If the store was full. 
AEE GSMSMS EFAILED, If the message could not be stored. 
AEE GSMSMS ENOSERVICE, if the device is not in GSM1x mod. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS SendMoreMemoryAvailable() 


Description: 


This function allows an application to send a GSM RP Layer SMMA message. This 
function is called in accordance with the GSM 23.040 spec. If the message times out, 
pReport->sendResult is set to AEE GSMSMS ETIMEDOUT. All other pReport fields 
are invalid. If the message is successfully sent, pReport->sendResult is set to 

AEE GSMSMS SUCCESS. 


Prototype: 


int IGSMSMS MoreMemoryAvailable 
( 
IGSMSMS *po, 

AEECallback *pCb, 
GSMSMSSMMAReport *pReport 
) 














Parameters: 
po: Pointer to the IGSMSMS object 
pCb: Pointer to AEECallback to call upon response message arrival 
pReport: Pointer to report structure to fill with response 


Return Value: 
If successful: AEE GSMSMS SUCCESS. 
If the message could not be sent: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS SendSMSDeliverReport() 


Description: 


This function allows an application to send a GSM SMS DELIVER REPORT 
message. This should be sent in response to receiving an SMS DELIVER message. 
The user would first fill outa GSMSMSDeliverReportType structure either manually or 
by calling IGSMSMS CreateDefaultMessage to fill in the structure and only modifying 
the parameters that are different from the default. For a simple 

SMS DELIVER REPORT message, this would typically be the 


UserData (GSMSMSSubmitType->UD) 
and the destination address 
(GSMSMSSubmitType->DA). 


Prototype: 


int IGSMSMS SendSMSDeliverReport 
( 
IGSMSMS *po, 
const GSMSMSDeliverReportType *pDeliverReport 
) 


Parameters: 


po Pointer to the IGSMSMS object 
pDeliverReport Pointer to the SMS Deliver Report message to send 


Return Value: 
If successful: AEE GSMSMS SUCCESS. 
If the the paremeters were not valid: AEE GSMSMS EBADPARAM 
If the message was not valid: AEE GSMSMS EFAILED 


Comments: 
None 
Return to the List of functions 
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IGSMSMS SendsMSSubmit() 


Description: 


This function allows an application to send a GSM SMS SUBMIT message. This can 
be used to send a SMS/EMS message and is also used for SIM toolkit. The user would 
first fill outa GSMSMSSubmitType structure either manually or by calling 

IGSMSMS CreateDefaultMessage to fill in the structure and only modifying the 
parameters that are different from the default. For a simple SMS SUBMIT message, 
this would typically be the Destination Address (DA) and the UserData (UD,UDL). 


When the SMS SubmitReport message is received, the pCB function will be called 
and the status can be retrieved from the GSMSMSSendReport structure. If a status 
report message was requested, the SMS StatusReport message will be delivered via 
the callback specified in the OnMTMessage registration. 


Prototype: 


int IGSMSMS SendSMSSubmit 

( 

IGSMSMS *po, 

const GSMSMSSubmitType * pMsg, 
ABECallback *pCb, 
GSMSMSSendReport *pReport 
) 














Parameters: 
po Pointer to the IGSMSMS object 
pMsg Pointer to the SMS Submit message to send 
pCb This callback will be invoked by AEE when the 
SMS SUBMIT REPORT is received. 
pReport Pointer to structure to be filled in reporting the submit status 


Return Value: 
AEE GSMSMS EBUSY if a transaction is pending 
AEE GSMSMS EBADPARAM if pMsg is NULL or pCb is NULL 
AEE GSMSMS EENCODE if the message could not be encoded 
AEE GSMSMS SUCCESS if successful 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS SetSCAddress() 


Description: 
This function updates the default SC address on the SIM. 


Prototype: 


void IGSMSMS SetSCAddress 
( 
IGSMSMS * po, 
const GSMSMSAddress *pAddress 
) 


Parameters: 
po Pointer to the IGSMSMS object 
pAddress Pointer to the structure to containing the new SC address 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the SC address could not be set: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSSMSMS SetMemoryCapExceededFlag() 


Description: 
This function updates the Memory Capacity Exceeded Flag on the SIM. In accordance 
with the GSM TS 11.11 spec, flag should be set to O ifthe MemCapExceded flag is set, 
and set to 1 if the it is not set. All other values are reserved. 


Prototype: 


void IGSMSMS SetMemoryCapExceededF lag (IGSMSMS * po, uint8 flag) 





Parameters: 
po: Pointer to the IGSSMSMS object 
pFlag: New setting for the MemCapExceded flag 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If flag is invaliid: AEE GSMSMS EBADPARAM 
If the flag could not be set: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS SetMessageStatus() 


Description: 
This function updates the status for a message in the specified store. 
It can be used to mark a : 
MT message as read or unread 
MO message as sent or not sent 
MO message as having a pending status report 
MO message as having a received status report 
MO message as having a stored status report 


Prototype: 


int IGSMSMS SetMesageStatus 
( 
IGSMSMS * po, 
uint16 index, 
GSMSMSStatusType status, 
GSMSMSStorageType writeTo 
) 


Parameters: 
po Pointer to the IGSMSMS object 
index Slot index of message to mark 
status The status to write 
writeTo Indicates whether to use the SIM or NVRAM database 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If writeTo is invalid: AEE GSMSMS EBADPARAM 
If the entry could not be updated: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS SetTPMR() 


Description: 
This function sets the last used TP-MR from EF-SMSS on the SIM. 


Prototype: 


int IGSMSMS Set TPMR(IGSMSMS * po, uint8 TPMR) 


Parameters: 
po: Pointer to the IGSSMSMS object 
TPMR: New value for the TP-MR in EF-SMSS on the SIM 


Return Value: 
If successful: AEE GSMSMS SUCCESS 
If the flag could not be read: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS StoreMessage() 


Description: 
This function stores a GSM SMS message on the specified store in the specified index. 


If *pIndex is setto GSMSMS STORE SIM before the call, a free slot will be 
selected and the value of *pIndex will be updated. Otherwise, the value of *pIndex 
will be used. 

lfthe storeTo parameter is setto GSMSMS STORE NVRAM the message will be 
stored in the first free slot in the NVRAM mailbox. 

If the storeTo parameter is set to storeTo GSMSMS STORE SIM, the message 
will be stored in the first free slot in the SIM. 

If the storeTo parameter is setto GSMSMS STORE NVRAM VM, the currently 
stored voicemail message is replaced with the specified voicemail message. 


Prototype: 


int IGSMSMS StoreMessage 
( 
IGSMSMS *po, 
const GSMSMSMsg * pMsg, 
GSMSMSStorageType storeTo, 
uintl6 *pIndex 
) 


Parameters: 
po Pointer to the IGSMSMS object 
pMsg Pointer to the GSM SMS Msg to store 
storeTo Indicates whether to store to the SIM or to NVRAM database 
pIndex Pointer to variable containing the index to to store the message at. Ifthe 


indexis setto GSMSMS INDEX ANY an index will be selected and the 
value of *pIndex will be updated. 


Return Value: 
If successful: AEE GSMSMS SUCCESS. 
If the store was full: AEE GSMSMS ESTORE FULL 
If the message could not be stored: AEE GSMSMS EFAILED 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IGSMSMS StoreStatusReport() 


Description: 


This function stores a GSM SMS StatusReport message that corresponds to a 
SMS Submit message stored at the specified slot on the SIM or in NVRAM. 


In GSM, the SMSR directory on the SIM contains the StatusReport. This entry contains 
an index into the SMS directory for the corresponding SMS Submit message. When 
the entry in the SMS directory is deleted, the corresponding entry in the SMSR is no 
longer valid. Therefore, the status report must be stored on the same store as the 
SMS Submit message. If the SMS Submit message is ever moved to another store, 


the SMS StatusReport must be moved at the same time or it will be lost. If the status 
report is stored in NVRAM only the portion of the message that would be saved to the 
SMSR is preserved. 


Prototype: 


int IGSMSMS StoreStatusReport 
( 
IGSMSMS *po, 
uint16 index, 
const GSMSMSMsg * pMsg, 
GSMSMSStorageType storeTo 
) 


Parameters: 
po Pointer to the IGSMSMS object 
index Pointer to slot index of the corresponding SMS Submit message 
pMsg Pointer to the GSM SMS Msg to store 
storeTo Indicates whether the SMS Submit message is on the SIM or in 


NVRAM database 


Return Value: 


If successful: AEE GSMSMS SUCCESS. 
If PMsg is NULL or storeTo is invalid: AEE GSMSMS EBADPARAM 
If the message could not be stored: AEE GSMSMS EFAILED 


Comments: 


None 


See Also: 


None 
Return to the List of functions 
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BREW provides a standardized and extensible data logging interface, which allows a BREW 
application developer to log data using a number of different transport mechanisms. 


Below are the primary logging transport implementations. A BREW application developer 
selects one by creating an ILogger instance with one of the following class IDs: 





Class ID Description 
AEECLSID LOGGER FILE Sends log items to a file. 
AEECLSID LOGGER WIN Sends log items to the Emulator output window. 


Each implementation is responsible for handling and writing to a specific transport but the data 
being sent is transport independent. 


The header file AEELoggerTypes.h provides definitions for the logging data types common to 
both BREW's ILogger interface and the PC side log parser in a client/server type of 


architecture. 


The file implementation outputs data to the output file in the following BREW packet format: 





BREW header Packet data 





The Windows implementation of the ILogger interface writes all outgoing logs to the BREW 
output window using the following format: 


bkt:xx typ:xx clD:xx ilD:xx FILENAME LINENUMBER MESSAGE ARGS 


in which 
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bkt 

typ 

clD 

ID 

FILENAME 
LINENUMBER 
MESSAGE 


ARGS 


ILogger Interface 


Log bucket 

Log type 

ClassiD of the currently running BREW application 
User-defined instance ID 

Optional file name where log was sent 

Optional line number where log was sent 

User defined text message 


Optional arguments using OEMLogger PutMsg() 


When compiling a release version of a BREW application, the constant AEE LOG DISABLE 
may be defined, which, using the preprocessor, removes all OEMLogger interface logging 
functions, except the instance creation and getting and setting parameters processes. This 
constant must be defined before a new BREW application includes AEELogger.h. 


The contents of log data is determined by the type element of the BREW Log header. Three 
standard log types are predefined by BREW, but the BREW application developer can also 
define as many custom log types as required. The three standard BREW-defined log types are 





as follows: 
Type Description Data contains 
AEE LOG TYPE TEXT ASClltextmessage Ifyou use this log type, the data contains 


nSize bytes of ASCII text. 


AEE LOG TYPE BIN MSG  AEELogTypeBinMsg Ifyou use this log type, the data contains one 


AEE LogTypeBinMsg structure. 


AEE LOG TYPE BIN BLK Block of arbitrary If you use this log type, the data contains 


binary data nSize bytes of arbitrary binary data. 
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Log items are sent and filtered in one of 255 distinct, general purpose buckets. These log 
buckets are filtered by the developer at run time using ILOGGER SetParam() and 
ILOGGER GetParam() or on the PC side, using a post processor. 


The structure AEELogTypeBinMsg contains the following elements: 


Element Description 





Header bT7,b6 — bits reserved 
b5,b4 — number of args 
b3 bit — file name present 
b2,b1,b0 — message level 


Line Line number in application code where this log 
item was sent 


args[ MAX LOG TYPE BIN MSG ARGS] Contains zero or more 32 bit integer values 


pszMsg[ MAX LOG TYPE BIN MSG TEXT SIZE] pszMsg contains two consecutive NULL 
terminated strings: the first is the file name 
where the log message was sent and the 
second is an ASCII text message 





List of Header files to be included 
The following header files are required: 
AEELogger.h 
AEELoggerTypes.h 


List of functions 


Functions in this interface include: 


ILOGGER AddRef() 
ILOGGER GetParam() 
ILOGGER Printf() 
ILOGGER Putltem() 
ILOGGER PutMsg() 
ILOGGER Release() 
ILOGGER SetParam() 


The remainder of this section provides details for each function. 
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ILOGGER AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
ILOGGER Release() 
Return to the List of functions 
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ILOGGER GetParam() 


Description: 
This function is called to get the configuration of the ILOGGER interface. Supported 
Parameters depends on the current implementations support. See 
AEELogParamType. 


Prototype: 


int ILOGGER GetParam 

( 

ILogger *pILogger, 
ALELogParamType pType, 
void* pParam 


) 

















Parameters: 
pILogger Pointer to the ILogger Interface object 
pType Parameter to modify 
pParam Pointer to be filled with settings parameter 


Return Value: 
SUCCESS Parameter handled successfully 
EBADPARM NULL parameter pointer 
EUNSUPPORTED Parameter type or option not supported 
EFAILED General failure, option not handled successfully 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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ILOGGER. Printf() 


Description: 
This function is called to send a formatted ASCII text message. 


ILOGGER Printf() is a MACRO that allows variable arguments. It must be called as 
follows: 


ILOGGER Print f( pMe->m pILogger, 
( pMe->m pILogger, 

USER BUCKETIA, 
“ FILE, 
(uint16) LINE 
"msg" r 

args ) ); 


Notice that the second argument is actually multiple arguments in parentheses, and 
args can be multiple comma separated values 














Prototype: 


int ILOGGER Printf 

( 

ILogger *pILogger, 
AFEELogBucket Type bucket, 
const char *pszFileName, 
uint16 nLineNum, 
const char *pszFormat, 

Ji 

















Parameters: 
pILogger, Pointer to the ILOGGER object 
bucket Bucket to place item 
pszFileName Name of file calling this function 
nLineNum Line number in file where it was called 


pszFormat ASCII text string similar to a printf format string 
Format string arguments 


Return Value: 

SUCCESS Log sent successfully 

EBADPARM Invalid pointer to pszFormat 

EUNSUPPORTED Log item filtered 

ENOMEMORY Unable to allocate required memory 

EFAILED Log not sent 

-- The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 
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Comments: 
None 


See Also: 
AEELogBucketType 
Return to the List of functions 
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ILOGGER PutMsg() 


Description: 


This function is called to send a predefined binary message and allows fast logging due 
to the limited formatting required and the fixed size of the outgoing log message. The 
outgoing binary message's data is of type structure AEELogBinMsgType, which is 
defined in AEELoggerTypes.h. 


Prototype: 


int ILOGGER PutMsg 
( 
ILogger *pILogger, 
AFEELogBucket Type bucket, 
const char *pszFileName, 
uint16 nLineNum, 
const char *pszMsg, 
uint8 nNumArgs, 
uint32 args[ MAX LOG TYPE BIN MSG ARGS ] 
) 




















Parameters: 
pIiLogger, Pointer to the ILOGGER object 
bucket Bucket to place item 
pszFileName ASCII NULL terminated name of file calling this function 
nLineNum Line number in file where it was called 
pszMsg ASCII NULL terminated text message 
nNumArgs length of the args array 
args array containing uint32 arguments 


Return Value: 

SUCCESS Log sent successfully 

EBADPARM Invalid pointer to pszMsg or nNumArgs too large 

EUNSUPPORTED Log item filtered 

ENOMEMORY Unable to allocate required memory 

EFAILED Log not sent 

-- The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 
AEELogBinMsgType 
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AEELogBucketType 
Return to the List of functions 
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ILOGGER Putltem() 


Description: 
This function is called to send a prioritized user defined binary message. Here are the 
steps to define a user log item type: 


1. Choose a user item number and define a meaningful name to it. 
Example: 

fdefine MY APPS LOG ITEM TYPE AEE LOG TYPE USER 1 
2. Define a structure that corresponds to you're new type, 
Example: 





























typedef struct( 

uint8 fool; 

uint32 foo2; 

uint8 fooString[ STRING SIZE 1]; 

+ myAppsItem; 
3. Enable the PC software that will be reading the logging output to recognize the log 
item type AEE LOG TYPE USER 1 (which in this case is 
MY APPS LOT ITEM TYPE) 


4. Call ILOGGER Putltem() with MY APPS LOG ITEM TYPE, a pointer to an 
instance of myAppsltem, and the size of myAppsltem. 





Prototype: 


int ILOGGER PutItem 

( 

ILogger *pILogger, 
ABEELogBucket Type bucket, 
AEELogItemType type, 
uintl6 nSize, 
uint8 *pItem 























Parameters: 
plLogger, Pointer to the ILOGGER object 
bucket Bucket to place item 
type User defined item type 
nSize Size of type in bytes 
pltem Pointer to instance of type 


Return Value: 
SUCCESS Log sent successfully 
EBADPARM Invalid pointer to pltem or size equal to zero 
EUNSUPPORTED Log item filtered 
ENOMEMORY Unable to allocate required memory 
EFAILED Log not sent 
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-- The following log codes only apply to file logging 


EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 
AEELogBucketType 
AEELogltemType 
Return to the List of functions 


335 


Erei ILogger Interface 


ILOGGER Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
ILOGGER AddRef() 
Return to the List of functions 
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ILOGGER SetParam() 


Description: 


This function is called to configure the performance and behavior of the ILOGGER 
interface. Supported parameters depend on the current implementation's support, see 
AEELogParamType for more information. 


Prototype: 


int ILOGGER SetParam 

( 

ILogger *pILogger, 
ALELogParamType pType, 
uint32 param, 
void* pParam 


) 

















Parameters: 
pILogger Pointer to the ILOGGER object 
pType Parameter to modify 
param New settings parameter 
pParam Pointer to new settings parameter 


Return Value: 

SUCCESS Parameter handled successfully 

EUNSUPPORTED Parameter type or option not supported 

EFAILED General failure, option not handled successfully 

EBADPARM NULL parameter pointer 

-- The following log codes only apply to file logging 
EFILENOEXISTS Output log file is closed 
EFILEEXISTS Output log file is open 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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This interface provides services for position determination using sector information or GPS 
information. In order to use the sector-based position determination methods such as 
IPOSDET GetSectorlnfo(), the sector information privileges are required. Similarly, for GPS 
based position determination methods such as IPOSDET SetGPSConfig(), 

IPOSDET GetGPSConfig(), and IPOSDET GetGPSInfo(), position determination privileges 
are required. 


IPOSDET GetGPSInfo() is an asynchronous method which use AEECallback. Care must be 
taken to ensure that the callbacks and information structures passed to these methods by 
reference remain in scope till the callback returns. Also, if multiple requests for sector 
information or GPS info. are made without waiting for the callbacks to return, the behavior of 
the interface will be unpredictable. 


BREW SDK users can set the GPS emulation in the Tools->GPS Emulation menu to use a 
pre-recorded NMEA file as GPS input, or connect an NMEA-output capable GPS device. An 
offline utility called NMEALogger.exe can be used to record an NMEA file from data coming 
from a GPS device connected to the serial port of the desktop/laptop. This NMEA file can be 
used later as GPS input. See SDK User's Guide and SDK Utilities Guide for details. 


List of Header files to be included 


The following header file is required: 


AEEPosDet.h 


List of functions 
Functions in this interface include: 


IPOSDET AddRef() 
IPOSDET GetGPSConfig() 
IPOSDET GetGPSInfo() 
IPOSDET GetOrientation() 
IPOSDET GetSectorlnfo() 
IPOSDET Querylnterface() 
IPOSDET Release() 
IPOSDET SetGPSConfig() 
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The remainder of this section provides details for each function. 
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IPOSDET AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IPOSDET Release() 
Return to the List of functions 
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IPOSDET GetGPSConfig() 


Description: 
This function gets the current GPS configuration of the GPS engine. 

















Prototype: 

int IPOSDET GetGPSConfig(IPosDet *pIPosDet, AEEGPSConfig *pConfig); 
Parameters: 

plPosDet [in] Pointer to the IPosDet Interface object. 

pCorfig [out] Pointer to GPS configuration. See AEEGPSConfig for 


details. 


Return Value: 
SUCCESS, if the function succeeded 
Error codes, if otherwise. 


EPRIVLEVEL, if the caller does not have PL POS LOCATION Pprivilege levels to 
invoke this function 


EBADPARM, if pConfig is NULL 
EUNSUPPORTED, if this function is not supported. 


Comments: 


Unless this function is called, the GPS engine is configured with default settings on the 
first call to IPOSDET GetGPsSlInfo(). Only the position determination requests 
following a call to IPOSDET SetGPSConfig() will use the new configurations. 
IPOSDET GetGPSInfo() requests pending response callbacks may not be affected by 
this method. 


See Also: 
AEEGPSCornfig 
IPOSDET SetGPSConfig() 
Return to the List of functions 
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IPOSDET GetGPSInfo() 


Description: 


This function returns information for GPS based position location. It returns latitude, 
longitude, altitude information, as well as vector information such as horizontal and 
vertical velocity, heading, and the uncertainty of the horizontal information. This is an 
asynchronous call, and the callback specified by pcb is called on completion. 



































BEEGPSAccuracy accuracy, 


Pointer to the IPosDet Interface object. 
Request type: 
AEEGPS GETINFO LOCATION, 
AEEGPS GETINFO VELOCITY, 
AEEGPS GETINFO ALTITUDE. 


The flags can be combined to get more than one type of 
information. 


Selected level of accuracy for this request. 


On input, this must be a valid pointer to the AEEGPSInfo 
structure. On callback, the members of this struct contain GPS 
information. The caller must ensure that this structure is valid till 
the callback specified by pcb gets called. 


Prototype: 
int IPOSDET GetGPSInfo 
( 
IPosDet *pIPosDet, 
ALEGPSReg reg, 
A 
ABEGPSInfo *pGPSInfo, 
AEECallback *pchb, 
) 
Parameters: 
piPosDet [in] 
reg [in] 
accuracy [in] 
pGPSInfo [out] 
pcb [in] 


Return Value: 


Callback function which gets called on completion of position 
determination. 


SUCCESS, if the function succeeded 


EPRIVLEVEL, if the caller does not have sufficient privilege levels 
(PL POS LOCATION) to invoke this function 


EBADPARM, if pGPSInfo or pcb is NULL 
EUNSUPPORTED, if this function is not supported. 


EFAILED, general failure 
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Comments: 
None 


See Also: 
AEEGPsSInfo 
Return to the List of functions 
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IPOSDET GetOrientation() 


Description: 


This function returns device's orientation in the horizontal plane. This is an 
asynchronous call, and the callback specified by pcb is called on completion. 


Prototype: 


int IPOSDET GetOrientation 
( 





IPosDet *pif, 
AEEOrientationInfo *pOrInfo, 
A 

) 

















EECallback *pcb, 


r 





Parameters: 

pif [in] The interface pointer. 

pOrinfo [out] On input, this must be a valid ptr to the AEE OrientationInfo 
structure with the member wSize indicating the space 
available in bytes. On callback, the members of this struct 
contain Orientation information. The caller must ensure that 
this structure is valid till the callback specified by pcb gets 
called. 

pcb [in] Callback function which gets called on completion of 


position determination. 


Return Value: 
SUCCESS: if the function succeeded 
EPRIVLEVEL: if the caller does not have sufficient privilege levels 
(PL POS LOCATION) to invoke this function 
EBADPARM: if pGPSlInfo or pcb is NULL 
EUNSUPPORTED: if this function is not supported. 
EFAILED: general failure 


Comments: 
None 


See Also: 
AEEOrientationinto 
Return to the List of functions 
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IPOSDET GetSectorlnfo() 


Description: 
This function returns information for sector-based position location, such as the 
SystemlD, NetworklD, BaseStationlD, BaseStationClass, and best Pilot. To invoke this 
function, the caller (application) must have the PL SECTORINFO privilege level. 
Without this privilege level, the function fails. 


Prototype: 


int IPOSDET GetSectorInfo 
( 





IPosDet * pIPosDet, 
AEESectorInfo * pSecInfo 
) 














Parameters: 
plPosDet [in] Pointer to the IPosDet Interface pointer. 
pSeclnfo [out] This must be a value pointer to the AEESectorlnfo structure. 
On return, the members of this struct contain sector 
information. 


Return Value: 
AEE SUCCESS, if the function succeeded. 
Error codes, if otherwise. 


EPRIVLEVEL, if the caller does not have sufficient privilege levels 
(PL SECTORINFO) to invoke this function. 


EUNSUPPORTED, if this function is not supported. 
EFAILED, general failure. 


Comments: 
None 


See Also: 
AEESectorinfo 
Return to the List of functions 
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IPOSDET Querylnterface() 


Description: 
This function asks an object for another API contract from the object in question. 


Prototype: 
int IPOSDET QueryInterface 
( 
IPosDet * pIPosDet, 
AEECLSID idReg, 
void * * ppo 


) 

















Parameters: 
plPosDet [in] Pointer to the IPosDet Interface object. 
idReqg [in] Requested ClassiD exposed by the object. 
ppo [out] Retumed object. Filled by this function. 


Return Value: 


SUCCESS, interface found. 

Error codes, if otherwise. 
ENOMEMORY, insufficient memory. 
ECLASSNOTSUPPORT, requested interface is unsupported. 


Comments: 
The pointer in *ppo is set to the new interface (with refcount positive), or NULL if the 
ClasslD is not supported by the object. 


See Also: 
None 
Return to the List of functions 
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IPOSDET Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IPOSDET AddRef() 
Return to the List of functions 
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IPOSDET SetGPSConfig() 


Description: 
This function sets the GPS configuration to be used by the GPS engine. 

















Prototype: 

int IPOSDET SetGPSConfig(IPosDet *pIPosDet, AEEGPSConfig *pConfig); 
Parameters: 

plPosDet Pointer to the IPosDet Interface object. 

pCorfig Pointer to GPS configuration. See AEEGPSCorfig for details. 


Return Value: 
SUCCESS, if the function succeeded 
Error codes, if otherwise. 
EPRIVLEVEL, if the caller does not have sufficient privilege levels 
(PL POS LOCATION) to invoke this function 
EBADPARM, if pConfig is NULL 
EUNSUPPORTED, if this function is not supported. 


Comments: 


Unless this function is called, the GPS engine is configured with default settings on the 
first call to IPOSDET GetGPsSlInfo(). Only the position determination requests 
following a call to IPOSDET SetGPSConfig() will use the new configurations. 
IPOSDET GetGPSInfo() requests pending response callbacks may not be affected by 
this method. 


See Also: 
AEEGPSCornfig 
IPOSDET GetGPSConfig() 
Return to the List of functions 
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IRingerMgr Interface 


The IRingerMgr interface provides the BREW interface with the abilityto manage ringers on 
the device. This interface is obtained by calling ISHELL Createlnstance() with 
AEECLSID RINGER. The class allows the caller to: 

* Create a ringer 

* Obtain a list of created ringers 

* Remove a ringer 

* Play a ringer 

* Obtain a list of supported ringer formats 

* Obtain a list of ringer categories 


* Set a category's ringer 


List of Header files to be included 


The following header file is required: 


AEERinger.h 
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List of functions 


Functions in this interface include: 


IRINGERMGR AddRef() 
IRINGERMGR Create() 
IRINGERMGR EnumCategorylnit() 
IRINGERMGR EnumNextCategory() 
IRINGERMGR EnumNextRinger() 
IRINGERMGR EnumRingerlnit() 
IRINGERMGR GetFormats() 
IRINGERMGR GetNumberFormats() 
IRINGERMGR GetRingerlD() 
IRINGERMGR GetRingerlnfo() 
IRINGERMGR RegisterNotify() 
IRINGERMGR Remove() 
IRINGERMGR SetRinger() 
IRINGERMGR Stop() 
IRINGERMGR Play() 
IRINGERMGR PlayEx() 
IRINGERMGR PlayFile() 
IRINGERMGR PlayStream() 
IRINGERMGR RegisterNotify() 
IRINGERMGR Release() 
IRINGERMGR Remove() 
IRINGERMGR SetRinger() 
IRINGERMGR Stop() 


The remainder of this section provides details for each function. 
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IRINGERMGR AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
IRINGERMGR Release() 
Return to the List of functions 
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IRINGERMGR Create() 


Description: 
This function creates a new ringer. 


Prototype: 


int IRINGERMGR Create 
( 
IRingerMgr * pIRingerMgr, 
const AECHAR * pszName, 
AEESoundPlayerFile format, 
IAStream * ps 

) 




















Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
pszName Name of the ringer. 
format Ringer format. 
ps Stream to ringer data. 


Return Value: 
SUCCESS, ringer is being created. 
EFAILED, Unable to create ringer 


Comments: 
None 


See Also: 
AEESoundPlayerFile 
Return to the List of functions 
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IRINGERMGR EnumCategoryInit() 


Description: 
This function initializes the enumeration context for category enumeration. 


Prototype: 


int IRINGERMGR EnumCategoryInit (IRingerMgr * pIRingerMgr) 














Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 


Return Value: 
SUCCESS, enumeration initialized. 
EFAILED, Unable to initialze enumeration 


Comments: 


There is one iteration for this function. Always call this before calling 
IRINGERMGR EnumNextCategory(). 


See Also: 
IRINGERMGR EnumNextCategory() 
Return to the List of functions 
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IRINGERMGR EnumNextCategory() 


Description: 
This function enumerates the next ringer category. 


Prototype: 
boolean IRINGERMGR EnumNextCategory 
( 














IRingerMgr * pIRingerMgr, 
AEERingerCat * pi 
) 














Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
pi Pointer to the ringer category information to fill. 


Return Value: 
TRUE, if successful. 
FALSE, if function fails or there are no more categories to enumerate. 


Comments: 


Always call IRINGERMGR EnumCategorylnit() before calling 
IRINGERMGR EnumNextCategory(). 


See Also: 
AEERingerCat 
IRINGERMGR EnumCategorylnit() 
Return to the List of functions 
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IRINGERMGR EnumNextRinger() 


Description: 
This function enumerates the next ringer. 


Prototype: 
boolean IRINGERMGR EnumNextRinger 
( 














IRingerMgr * pIRingerMgr, 
AEERingerInfo * pi 
) 














Parameters: 
plRingerMgr [in] Pointer to the IRingerMgr Interface object. 
pi [out] Pointer to the ringer information to fill. 


Return Value: 
TRUE, if successful. 
FALSE, Failed to enumerate next ringer 


Comments: 
Always call IRINGERMGR EnumRingerlnit() before calling this. 


See Also: 
AEERingerlnfo 
IRINGERMGR EnumRingerlnit() 
Return to the List of functions 
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IRINGERMGR EnumRingerlnit() 


Description: 
This function initializes enumeration of the list of ringers. 


Prototype: 


int IRINGERMGR EnumRingerInit (IRingerMgr * pIRingerMgr) 














Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 


Return Value: 
SUCCESS, enumeration initialized. 
EFAILED, Unable to initialize enumeration. 
Other implementation-specific error codes 


Comments: 


There is one iteration for this function. Always call this before calling 
IRINGERMGR EnumNextRinger(). 


See Also: 
IRINGERMGR EnumNextRinger() 
Return to the List of functions 
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IRINGERMGR GetFormats() 


Description: 
This function fills a list of the supported ringer formats. 


Prototype: 

int IRINGERMGR GetFormats 
( 
IRingerMgr * pIRingerMgr, 
AEESoundPlayerFile * pwFormats, 
int nCount 


) 

















Parameters: 


plRingerMgr [in] Pointer to the IRingerMgr Interface object. 

pwFormats [out] 'Pointerto a list of formats of size nCount * 
sizeof(AEE SoundPlayerFile). 

nCount [in] Number of format entries to fill. 


Return Value: 
SUCCESS, buffer filled with ringer format entries. 
Other error codes. 
EFAILED, Size of retum buffer is invalid. 


Comments: 
None 


See Also: 
AEESoundPlayerFile 
IRINGERMGR GetNumberFormats() 
Return to the List of functions 
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IRINGERMGR GetNumberFormats() 


Description: 
This function retrieves the number of ringer formats supported on the device. 


Prototype: 


int IRINGERMGR GetNumberFormats (IRingerMgr * pIRingerMgr) 





Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 


Return Value: 
Number of ringer formats supported. 


Comments: 
None 


See Also: 
IRINGERMGR GetFormats() 
Return to the List of functions 
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IRINGERMGR GetRingerlD() 


Description: 
This function returns the ringer ID for a ringer given the file name. 


Prototype: 


AEERingerID IRINGERMGR GetRingerID 
( 

IRingerMgr * pIRingerMgr, 
const char * pszFile 


) 

















Parameters: 


plRingerMgr Pointer to the IRingerMgr Interface object. 
pszFile Root file name of ringer. 


Return Value: 
AEERingerlD of the ringer specified. 
AEE RINGER ID NONE, if the function fails. 


Comments: 
None 


See Also: 
AEERingerlD 
AEERingerlnfo 
Return to the List of functions 
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IRINGERMGR GetRingerlnfo() 


Description: 
This function retrieves information about the specified ringer. 


Prototype: 


int IRINGERMGR GetNumberFormats 























( 
IRingerMgr * pIRingerMgr, 
AEERingerID id, 
AEERingerInfo * pi 
) 
Parameters: 
plRingerMgr [in] Pointer to the IRingerMgr Interface object. 
id [in] Ringer ID. 
pi [out] Pointer to the ringer info structure to fill. 


Return Value: 
SUCCESS, ringer information valid. 
Other error codes. 
EFAILED, invalid ringer ID, or pi is NULL. 


Comments: 
None 


See Also: 
AEERingerlD 
AEERingerlnfo 
Return to the List of functions 
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IRINGERMGR Play() 


Description: 
This function plays an installed ringer. 


Prototype: 

int IRINGERMGR Play 
( 
IRingerMgr * pIRingerMgr, 
AEERingerID id, 
uint32 dwPause 


) 

















Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
id Ringer ID to play. 
dwPause Time to pause between replays; O (zero) if single play. 


Return Value: 
SUCCESS, ringer begins playing. 
EFAILED, invalid ringer. 
Other implementation-specific error codes. 


Comments: 
None 


See Also: 
AEERingerlD 
IRINGERMGR Stop() 
Return to the List of functions 
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IRINGERMGR PlayEx() 


Description: 


This function plays the specified ringer using the following items, in order, as the 
source: 


* An installed ringer ID 
* An input file name 
* An input IAStream object 


The action allows the caller to test ringers before placing them in the ringer directory. 


Prototype: 


int IRINGERMGR PlayEx 
( 
IRingerMgr * pIRingerMgr, 
AEERingerID id, 

const char * pszFile, 
IAStream * pStream, 
uint32 dwPause 


) 




















Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
id Ringer ID to play. 
pszFile Input file name. 
pStream Input stream. 
dwPause Time to pause between replays; O (zero) if single play. 


Return Value: 
SUCCESS, ringer begins playing. 
EFAILED, Invalid ID, input file name, stream, or unable to play ringer. 


Comments: 
None 


See Also: 
AEERingerlD 
IRINGERMGR Stop() 
Return to the List of functions 
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IRINGERMGR PlayFile() 


Description: 
This function plays a ringer when given an input file name. This action allows the caller 
to test ringers before placing them in the ringer directory. 


Prototype: 


int IRINGERMGR PlayFile 
( 
IRingerMgr * pIRingerMgr, 
const char * pszFile, 
uint32 dwPause 


) 





Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
pszFile Input file name. 
dwPause Time to pause between replays (0 if single play). 


Return Value: 
SUCCESS, ringer begins playing. 
EFAILED, invalid input file name or unable to play ringer. 
Other implementation-specific error codes. 


Comments: 
None 


See Also: 
IRINGERMGR Stop() 
Return to the List of functions 
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IRINGERMGR PlayStream() 


Description: 


This function plays the specified ringer using an input IAStream Interface object, 
allowing the caller to test a ringer that may be located in a file (IFile Interface), in 
memory (IMemAStream Interface), or through the network (ISocket Interface). 


Prototype: 


int IRINGERMGR PlayStream 
( 
IRingerMgr * pIRingerMgr, 
IAStream * pStream, 
uint32 dwPause 


) 





Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
pStream Input file name. 
dwPause Time, in milliseconds, to pause between replays; O (zero) if single play. 


Return Value: 
SUCCESS, ringer begins playing. 
EFAILED, invalid input stream or unable to play ringer. 
Other implementation-specific error codes. 


Comments: 
This function only supports network stream from TCP socket but not UDP socket. 


See Also: 
None 
Return to the List of functions 
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IRINGERMGR RegisterNotify() 


Description: 
This function registers or deregisters a notification callback when playback or creation 
events are complete. 


Prototype: 
void IRINGERMGR RegisterNotify 
( 
IRingerMgr * pIRingerMgr, 
PENRINGEREVENT pfn, 
void * pUser 


) 




















Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
pfn Pointer to the user callback (NULL to deregister). 
pUser Pointer to user data for callback. It can be NULL if no identifying data is 


required. 


Return Value: 
None 


Comments: 
None 


See Also: 
PFNRINGEREVENT 
Return to the List of functions 
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IRINGERMGR Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
IRINGERMGR AddRef() 
Return to the List of functions 
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IRINGERMGR Remove() 


Description: 
This function removes the specified ringer. 


Prototype: 


int IRINGERMGR Remove (IRingerMgr * pIRingerMgr, AEERingerID id) 

















Parameters: 


plRingerMgr Pointer to the IRingerMgr Interface object. 
id Ringer ID. 


Return Value: 
SUCCESS, ringer removed. 
EFAILED, invalid ringer ID or unable to remove ringer. 
Other implementation-specific error codes. 


Comments: 
This function cannot be used to remove OEM installed ringers. 


See Also: 
AEERingerlD 
Return to the List of functions 
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IRINGERMGR SetRinger() 


Description: 
This function allows the caller to to set a ringer for the specified category. 


Prototype: 


int IRINGERMGR SetRinger 























( 
IRingerMgr * pIRingerMgr, 
AEERingerCat ID idCat, 
AEERingerID id 
) 
Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 
idCat Category for the ringer. 
id ID of the ringer. 


Return Value: 
SUCCESS, ringer set. 
Other error codes. 
EFAILED, ringer not set. 


Comments: 
None 


See Also: 
AEERingerlD 
AEERingerCatID 
IRINGERMGR EnumNextCategory() 
Return to the List of functions 
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IRINGERMGR Stop() 


Description: 
This function terminates the playback of a ringer. 


Prototype: 


int IRINGERMGR Stop (IRingerMgr * pIRingerMgr) 





Parameters: 
plRingerMgr Pointer to the IRingerMgr Interface object. 


Return Value: 
SUCCESS, ringer is stopping. 
Other error codes. 
EFAILED, no ringer is playing. 


Comments: 
None 


See Also: 
IRINGERMGR Play() 
Return to the List of functions 
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IRUIM Interface 


The Interface provides 


List of Header files to be included 


The following header file is required: 


AEERUIM.h 
List of functions 


Functions in this interface include: 


IRUIM AddRef() 

IRUIM CHVDisable() 
IRUIM CHVEnable() 
IRUIM GetCHVStatus() 
IRUIM Getld() 

IRUIM GetPrefLang() 
IRUIM IsCardConnected 
IRUIM PINChange() 
IRUIM PINCheck() 
IRUIM Querylnterface() 
IRUIM Release() 

IRUIM UnblockCHV() 
IRUIM VirtualPINCheck() 
OEMRUIMAddr GetFuncs() 


The remainder of this section provides details for each function. 
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IRUIM AddRef() 


Description: 
This function increments the reference count of the IRUIM Interface object, allowing 
the object to be shared by multiple callers. The object is freed when the reference 
count reaches O (zero). 


Prototype: 


uint32 IRUIM AddRef (IRUIM *pIRUIM) 


Parameters: 
pIRUIM: [in]. Pointer to the IRUIM Interface object. 


Return Value: 
Incremented reference count for the object. 


Comments: 
A valid object returns a positive reference count. Otherwise, O (zero) is returned. 


See Also: 
IRUIM Release() 
Return to the List of functions 
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IRUIM CHVDisable() 


Description: 
This function will disable CHV1 if the last call to IRUIM PINCheck() was successful. 


Prototype: 


int IRUIM CHVDisable (IRUIM *pIRUIM) 


Parameters: 
pIRUIM: [in]. Pointer to the IRUIM Interface object. 


Return Value: 
AEE SUCCESS if CHV1 was disabled, 
EFAILED otherwise or other OEM specified error code 


Comments: 


The successful completion of this command allows unprotected access to all files 
protected by CHV1. Ths function performs the DISABLE CHV functionality as 
described in 3GPP TS 11.11. 


See Also: 
None 
Return to the List of functions 


372 


Erevi IRUIM Interface 


IRUIM CHVEnable() 


Description: 
This function will enable CHV1 if the passed in PIN is correct. 





Prototype: 

boolean IRUIM CHVEnable (IRUIM *pIRUIM, const char *pPin) 
Parameters: 

pIRUIM Pointer to the IRUIM Interface object. 

pPin Pointer to an eight digit character string. If NULL, use the PIN 


previously entered with IRUIM PINCheck(). This does not need to be 
NULL terminated. 


Return Value: 
TRUE, if CHV1 was enabled, 
FALSE, if otherwise 


Comments: 


If CHV1 has been disabled, you need to include the CHV1 as the argument to this 
function since the 'ENABLE CHV1' command requires it. If CHV1 is enabled, the user 
will have already entered CHV1 so you do not need to include it as an argument (pass 
in NULL). This function performs the ENABLE CHV functionality as described in 3GPP 
TS 11.11. Ifthe operation returns TRUE, the PIN is stored and will be used for the next 
call to IRUIM VirtualPINCheck(). 


See Also: 
IRUIM PINCheck() 
IRUIM VirtualPINCheck() 
Return to the List of functions 
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IRUIM GetCHVStatus() 


Description: 
This function returns the current R-UIM status 


Prototype: 


int IRUIM GetCHVStatus (IRUIM *pIRUIM, AEECHVStatus *pCHVStatus) 














Parameters: 
pIRUIM: [in]. Pointer to the IRUIM Interface object. 
pCHVsStatus: [out]. Pointer to the returned CHV status. 


Return Value: 
AEE SUCCESS if operation succeeded 
EFAILED otherwise or other OEM specified error code 


Comments: 
None. 


See Also: 
None 
Return to the List of functions 
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IRUIM Getld() 


Description: 
This function returns the identification number of the R-UIM. 


Prototype: 
int IRUIM Get Id(IRUIM *pIRUIM, char *pId, int *pnLen) 
Parameters: 
pIRUIM [in] Pointer to the IRUIM Interface object. 
pld [in/out] Card ID. If set to NULL when called, then pnLen will contain 
the required size of the ID when the function returns. 
pnLen [in/out] If pldis NULL when this function is called, pnLen will return 


the number of bytes required to hold the entire ld. 
Otherwise, pnLen should be set to the number of bytes 
requested and will return the number of bytes actually 
provided. 


Return Value: 
AEE SUCCESS if no problem occurred 
ENOMEMORY - Insufficient memory 
Or other OEM specified error code 


Comments: 
None. 


See Also: 
None 
Return to the List of functions 
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IRUIM GetPrefLang() 


Description: 
This function returns the highest priority preferred language on the R-UIM card. 


There may be a second, third,...,nth preferred language on theR-UIM. This function will 
only return the first preferred langauge. 


Prototype: 


int IRUIM GetPrefLang(IRUIM *pIRUIM, int *pLang, int *pEncoding) 





Parameters: 
pIRUIM: [in]. Pointer to the IRUIM Interface object. 
pLang: [out]. Most preferred langauge retumed from the R-UIM. 
pEncoding: [out]. Encoding of the most preferred language. 


Return Value: 
None 


Comments: 
AEE SUCCESS if no problems occurred, 
EBADPARM - Parameters invalid 
ENOMEMORY - Insufficient memory 
Or other OEM specified error code 


See Also: 
None 
Return to the List of functions 
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IRUIM IsCardConnected 


Description: 
This function checks to see if the R-UIM card is present. 


Prototype: 

boolean IRUIM IsCardConnected (IRUIM *pIRUIM) 
Parameters: 

pIRUIM Pointer to the IRUIM Interface object. 


Return Value: 
TRUE if a R-UIM card was found, 
otherwise FALSE. 


Comments: 
FALSE will be returned if the card is not initialized, is powered down, or is faulty. 


See Also: 
None 
Return to the List of functions 
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IRUIM PINChange() 


Description: 


This function will change the designated CHV on the R-UIM to the PIN passed in. 
IRUIM PINCheck() or another command that sets the virtual pin must be called before 
this command. 


Prototype: 


int IRUIM PINChange 


IRUIM *pIRUIM, 
AEECHVType chv, 
const char *pPin 














Parameters: 
pIRUIM Pointer to the IRUIM Interface object. 
chv PIN to be checked. 
pPin Pointer to an eight digit character string to be used as the new PIN. This 


does not need to be NULL terminated. 


Return Value: 
AEE SUCCESS ifthe PIN was changed, 
EFAILED Or other OEM specified error code 


Comments: 


The appropriate CHV must be enabled and not blocked when this function is called. 
This function performs the CHANGE CHV functionality as described in 3GPP TS 11.11. 
If the operation returns AEE SUCCESS, the new PIN will be stored and used for the 
next call to IRUIM VirtualPINCheck(). 


See Also: 
IRUIM PINCheck() 
IRUIM VirtualPINCheck() 
Return to the List of functions 
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IRUIM PINCheck() 


Description: 
This function will compare the designated CHV on the R-UIM with the PIN passed in. 














Prototype: 
boolean IRUIM PINCheck (IRUIM *pIRUIM, AEECHVType chv, const char 
*pPin) 
Parameters: 
pIRUIM Pointer to the IRUIM Interface object. 
chv PIN to be checked. 
pPin Pointer to an eight digit character string. 


Return Value: 
TRUE if the user input matches the CHV on the R-UIM, otherwise FALSE. 
FALSE will be returned ifis NULL. 


FALSE will also be returned if the RIUM is not connected as defined above in the 
description of IRUIM IsCardConnected(). 


Comments: 


The appropriate CHV must be enabled and not blocked when this function is called. 
This function performs the VERIFY CHV functionality as described in 3GPP TS 11.11. 
If the operation returns TRUE, the PIN is stored and will be used for the next call to 
IRUIM VirtualPINCheck(). 


See Also: 
IRUIM VirtualPINCheck() 
Return to the List of functions 
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IRUIM Querylnterface() 


Description: 


This function retrieves a pointer to an interface conforming to the specified class ID. 
This can be used to query for extended functionality, like future versions or proprietary 
extensions. Upon a successful query, the interface is returned after the AddRef 
methodis called. The caller is responsible for call the Release method at some point in 
the future. 


Prototype: 


int IRUIM QueryInterface 

(IRUIM *pIRUIM, 
ABECLSID idReg, 
void **ppo) 














Parameters: 
pIRUIM [in] Pointer to the IRUIM Interface object. 
idReq [in] Requested class ID exposed by the object 
ppo [out] Returned object. Filled by this method 


Return Value: 
AEE SUCCESS - Interface found 
ENOMEMORY - Insufficient memory 
ECLASSNOTSUPPORT - Requested interface is unsupported 
EFAILED - Any general failure. 
Or other OEM specified error code 


Comments: 


The pointer in *ppo is set to the new interface (with refcount positive), or NULL if the 
ClassID is not supported by the object. This function can be called with idReq = 
AEECLSID ADDRBOOK to return an address book object. However, CHV1 must 
have been previously disabled or verified before this function is called. 


The ppo MUST not be NULL. 


See Also: 
IRUIM CHVDisable() 
IRUIM PINCheck() 
IAddrBook Interface 
Return to the List of functions 
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IRUIM Release() 


Description: 
This function decrements the reference count of the IRUIM Interface object. The object 
is freed from memory and is no longer valid when the reference count reaches O (zero). 


Prototype: 


uint32 IRUIM Release (IRUIM *pIRUIM) 


Parameters: 
pIRUIM: [in]. Pointer to the IRUIM Interface object. 


Return Value: 
Decremented reference count for the object. 
O (zero), If the object has been freed and is no longer valid. 


Comments: 
None 


See Also: 
IRUIM AddRef() 
Return to the List of functions 
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IRUIM UnblockCHV() 


Description: 
This function will unblock a CHV which has been previously blocked using the passed 
in unblock CHV and PIN. An application must have PL SYSTEM privilege complete 
this function. 


Prototype: 
int IRUIM UnblockCHV(IRUIM *pIRUIM, 
AEECHVType chv, 
char *pUnblockPin, 
char *pPin) 














Parameters: 
pIRUIM Pointer to the IRUIM Interface object. 
chv PIN to be unblocked. 


pUnblockPin Pointer to an eight digit character unblock string.This does not need to 
be NULL terminated. 

pPin Pointer to an eight digit character string. This does not need to be NULL 
terminated. 


Return Value: 
AEE SUCCESS if the user input was valid. 
EPRIVLEVEL if the calling application. does not have PL SYSTEM privilege. 
EFAILED for other errors 


Comments: 


CHV1 will be restored to a the pPin value. This function performs the UNBLOCK CHV 
functionality as described in 3GPP TS 11.11. Ifthe operation returns AEE SUCCESS, 
the PIN is stored and will be used for the next call to IRUIM VirtualPINCheck(). 


See Also: 
None 
Return to the List of functions 
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IRUIM VirtualPINCheck() 


Description: 
fFIRUIM PINCheck() has been previously called, this function can be used to re-verify 
the CHV1 PIN without accessing the R-UIM. It compares the input PIN with the 
previous PIN value. 


Prototype: 


boolean IRUIM VirtualPINCheck 
(IRUIM *pIRUIM, 

AEECHVType chv, 

const char *pPin 














Parameters: 
pIRUIM: [in]. Pointer to the IRUIM Interface object. 
chv: [in]. PIN to be checked. 
pPin: [in]. Pointer to the eight digit character string. 


Return Value: 


TRUE if the user input matches the previously read value of CHV1 on the R-UIM, 
otherwise FALSE. 


FALSE FALSE will be returned if is NULL. 


FALSE will also be returned if the R-UIM is not connected as defined above in the 
description of IRUIM IsCardConnected(). 


Comments: 


This function should only be called after IRUIM PINCheck() has been called 
successfully. 


See Also: 
IRUIM PINCheck() 
Return to the List of functions 
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OEMRUIMAddr GetFuncs() 


Description: 


This function is called when the BREW AddressBook interface is created with a class 
ID of AEECLSID RUIM. This function returns the OEM RUIM functions that are 
needed by the IAddrBook interface to access the R-UIM phonebook. 


Prototype: 


VTBL (IOEMAddrBook) *0OEMAddrBook Init (void); 








Parameters: 
None 


Return Value: 


Returns the table of OEMRUIM functions needed by the IAddrBook interface to access 
the R-UIM phonebook. 


Comments: 
None 


See Also: 
IRUIM Querylnterface() 
Return to the List of functions 


384 


brew. 


ITAPI Interface 


TAPlI is a simple interface to the telephony layer in the device. It provides the following 
services: 


- Retrieving Telephony status 

- Placing voice calls 

- Extracting SMS text ffom SMS messages 

- Obtaining caller ID on incoming/in-progress calls 
- Registering for SMS Messages 


The ITAPI interface is obtained via the ISHELL Createlnstance mechanism. 


Notifications Sent by this Class: 
The TAPI class allows applications to register for the following Notifications: 
a. NMASK TAPI STATUS 


b. NMASK TAPI SMS TEXT 
c. NMASK TAPI SMS TS 


Receiving SMS Messages: 

BREW Applications can register to be notified when a SMS message comes to the system. 
This registration can be done in the MIF. When the message comes into the system, 
applications that have registered to be notified receive the EVT NOTIFY event. The dwParam 


of this event contains detailed information about the message. 


The following masks can be used to register for SMS Notifications through BREW: 
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1. NMASK TAPI SMS TEXT: This allows applications to register for all Text Messages 
(messages with TeleServce ID: SMS TELESERVICE CMT 95). When a text message 
arrives, the application is notified through the EVT NOTIFY event. The dwParam of this event 
is of type AEENotify. The pData member in this AEENotify Structure will be of type 
AEESMSTextMsg and contains the actual text message. 


2. NMASK TAPI SMS TS: This allows applications to register for SMS message of a specific 
TeleService ID. To construct the actual 32-bit mask to be used in the MIF for the registration, 
the upper 16 bits of the mask must contain the TeleService ID value and the lower 16 bits must 
contain the value 0x0004 (which corresponds to NMASK TAPI SMS TS). 


Example: 

To register for a message with TS ID: 0x1002, the 32-mask should be: 0x10020004 
Applications can register for multiple messages by creating the 32-mask for each message. 
Example: 


To register for messages with TS IS: 1002 and 1003, the application must register two 
separate masks: 0x10020004 and 0x10030004. 


When the SMS message of this TS ID is received by the system, the application is notified 
through the EVT NOTIFY event. The dwParam of this event is of type AEENotify. The pData 
member in the AEENotify Structure is of type AEESMSMsg. This structure contains detailed 
information about the message. 


Registering for Device Status Change: 
NMASK TAPI STATUS: Applications can use the TAPI class to be notified whenver there is 
a change in the telephony status of the device. To register for this notification, applications 


must use the mask NMASK TAPI STATUS. 


Whenever there is a status-change, applications receive the EVT NOTIFY event. The 
dwParam of this event is of type AEENotify. 


The pData member inside this AEE Notify structure is of type TAPIStatus and contains detailed 
information about the current telephony status of the device. 
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List of Header files to be included 


The following header file is required for ITAPI 


AEETAPI.h 
List of functions 


Functions in this interface include: 


ITAPI AddRef() 

ITAP| ExtractSMSText() 
ITAPI GetCallerlD() 
ITAPI GetStatus() 

ITAPI IsDataSupported() 
ITAPI IsVoiceCall() 
ITAPI MakeVoiceCall() 
ITAPI OnCallStatus() 
ITAPI OnCallEnd() 
ITAPI Release() 

ITAPI SendSMS() 


The remainder of this section provides details for each function. 
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ITAPI AddRef() 


Description: 
This function is inherited from IBASE AddRef() 


See Also: 
ITAPI Release() 
Return to the List of functions 
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ITAPI ExtractSMS Text() 


Description: 


This function extracts the formatted text from a raw SMS message. The format of the 
input parameter is an AEESMSMsg. 


The typical means to use this function: 


* When applications register for a text message by using the notification mask 
NMASK TAPI SMS TS and by specifying the TeleService ID as 
SMS TELESERVICE CMT 95, the application gets notified using the 
EVT NOTIFY mechanism. 


* The dwParam to this event is oftype AEE Notify. The pData inside the AEENotify 
structure is of type AEESMSMsg. 


* For text messages, this function ITAPI ExtractSMSText() can be invoked using 
this AEESMSMsg so as to extract the actual text portion of the message. 


* A recommended way for applications to register for text messages is using the 
notification mask: NMASK TAPI SMS TEXT. 


* When this mask is used, the pData inside the AEENotify structure received 
during the notification is already of type AEESMS TextMsg and contains the 
actual text of the message. 


Prototype: 


AEESMSTextMsg * ITAPI ExtractSMSText 
( 
ITAPI * pITAPI, 
const AEESMSMsg * pMsg 
) 














Parameters: 
pITAPI Pointer to the ITAPI Interface object. 
pMsg Pointer to the input AEESMSMsg. 


Return Value: 
NULL, if this function fails. 


If successful, this function returns a pointer to AEESMSTextMsg containing the actual 
text. This buffer is valid until the next call to ITAPI ExtractSMSText() or until the 
interface is released. 


Comments: 
None 


See Also: 
AEESMSMsg 
AEESMSTextMsg 
Return to the List of functions 
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ITAPI GetCallerlD() 


Description: 
This function retrieves the ID, in digits, of an incoming or outgoing voice call. 





Prototype: 

boolean ITAPI GetCallerID(ITAPI * pITAPI, AECHAR * pDest, int nSize) 
Parameters: 

pITAPI Pointer to the ITAPI Interface object. 

pDest Destination pointer. 

nSize Size in bytes of the destination buffer. 


Return Value: 
TRUE, if call in progress and buffer filled. 
FALSE, if no call in progress or invalid buffer. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITAPI GetStatus() 


Description: 
This function obtains the current status of the telephony device, including service and 
call status. Applications can also register to receive updated TAPIStatus information on 
any changes through the ISHELL RegisterNotify() function. 


Prototype: 

int ITAPI GetStatus(ITPAI * pITAPI, TAPIStatus * ps) 
Parameters: 

pITAPI Pointer to the ITAPI Interface object. 

ps Pointer to the status information to be filled. 


Return Value: 
SUCCESS, if valid status information. 
EBADPARM, if bad parameter. 


Comments: 
None 


See Also: 
TAPIStatus 
ISHELL RegisterNotify() 
Return to the List of functions 
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ITAPI IsDataSupported() 


Description: 
This method can be used to determine whether the handset supports data service. 


Prototype: 

boolean ITAPI IsDataSupported(ITapi *pITAPI) 
Parameters: 

pITAPI Pointer to the ITAPI object 


Return Value: 


TRUE, if the handset supports data service 
FALSE, if the handset does not support data service 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITAPI IsVoiceCall() 


Description: 
This method can be used to determine whether the current call in the system is a voice 
call. 
Prototype: 
boolean ITAPI IsVoiceCall(ITapi *pITAPI) 
Parameters: 
pITAPI Pointer to the ITAPI object 


Return Value: 
TRUE, if the current call is a voice call 
FALSE, if the current callis NOT a voice call 


Comments: 
None 


See Also: 
ITAPI MakeVoiceCall() 
Return to the List of functions 
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ITAPI MakeVoiceCall() 


Description: 


This method is called to place a voice call. The number dialed is specified in the digits 
string. No call is placed if the input string is empty or NULL. Only the following digits 
are allowed: 0-9, &, *. All other digits are ignored. If a voice call is in progress 
EALREADY is returned. If a data call is in progress and no network activity is in- 
progress (TCP), the data call is ended and the call is placed. 


This function enforces the privacy policies established by the carrier. This may include 
intermediate prompts to the user using dialogs. 


Typically, when this function is invoked, a dialog is displayed to the user requesting 
whether it is OK to place a call. When the user clicks “YES”, the call is placed. 


The event flow to the application when this function is invoked: 


1. A dialog is displayed to the user. 

2. When that dialog is dismissed, the event EVT DIALOG END is sent to the 
application. 

3. Atthis point, the application must re-draw the screen. 

4. If user accepted to place the call, the event EVT APP SUSPEND is sentto the 
application. 

5. When the call finishes, the event EVT APP RESUME is sent to the application. 

6. The application must re-draw the screen. 

Prototype: 


int ITAPI MakeVoiceCall 


( 

ITAPI * pITAPI, 

const char * pszNumber, 
AEECLSID clsReturn 

) 

















Parameters: 
pITAPI Pointer to the ITAPI Interface object 
pszNumber Pointer to number to dial 
clsReturn Classid of the applet to be run when the call is completed 


Return Value: 
SUCCESS, if the function is in progress. 
EBADPARM, if the number is invalid. 
EALREADY, if there is a voice call already in progress. 
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Comments: 
If cisReturn is O, the current application will be resumed. 


When ITAPI MakeVoiceCall is invoked. After the privacy dialog is selected by user - 
EVT DIALOG ENDiis sent to the application with dwParam indicating the response. 
The dwParam has 1 for a "Yes" response and 2 for "No" response from user 


See Also: 
AEECLSID 
Return to the List of functions 
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ITAP| OnCallEnd() 


Description: 
This method is identical to ITAP| OnCallStatus(). 


Prototype: 

int ITAPI OnCallEnd 
( 
ITAPI * pITAPI, 
PENNOTIFY pÊfn, 
void * pUser, 
uint32 dwDelay, 
uint1l6 wFlags 
) 





Parameters: 
See ITAP| OnCallStatus() 


Return Value: 
See ITAP| OnCallStatus() 


Comments: 
None 


See Also: 
See ITAP| OnCallStatus() 
Return to the List of functions 
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ITAPI OnCallStatus() 


Description: 


This method can be used to register a Callback function that will be invoked by BREW 
when there is a change in the call-status. It supports flags that can be used to specify 
what type of call-states the application cares about. 


Prototype: 


int ITAPI OnCallStatus 

( 

ITAPI * pITAPI, 
PENNOTIFY pÊfn, 
void * pUser, 
uint32 dwDelay, 
uint1l6 wFlags 

) 


Parameters: 

pITAPI Pointer to the ITAPI object 

pfn Notification function to be called when any call-status changes 

pUser User Data to be passed to the notification function when it is invoked. 

dwDelay The time period in milliseconds BREW waits after the call-state has 
changed and before notifying the application 

wFlags The following flags are supported: 
OCS CANCEL Cancel a previously registered Callback 

Function 


OCS UNIQUE PFN When this flag is set, any previous 
registrations of the same callback function 
with different data pointers are cancelled. 

OCS ONE SHOT Informs BREW that this CB function is to be 
registered for just one notification. Once a 
single call-status change occurs, this 
notification is invoked and the CB function is 
removed from the internal list. This CB will 
not longer be invoked. 


OCS INCOMING Register for notifications when there is an 
incoming call 
OCS ORIG Register for notifications when call- 


originations happen 
OCS CONVERSATION Register for notifications when call enters the 
conversation state (i.e. Two way state) 


OCS IDLE Register for notifications when the call is 
ended 
OCS OFFLINE Register for notifications when the device 


loses coverage 
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OCS ALL Register for all call-state transitions 
(incoming, orig, conversation, idle) 


Return Value: 
SUCCESS, if successfully registered 
ENOMEMORY, if failed 


Comments: 
None 


See Also: 
None 
Return to the List of functions 


398 


revi ITAPI Interface 


ITAPI Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
ITAPI AddRef() 
Return to the List of functions 
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ITAP| SendsMS() 


Description: 


This method is used to send SMS messages from the handset.This function can be 
used to send text messages to either a specific BREW application on another handset 
or a general text message to the handset. It sends messages to a destination mobile 
number or an email ID. When this function is called, it is likely that it will resultin a 
SUSPEND/RESUME sequence to the BREW application. This is initiated by the 
handset when it sends the SMS message out. 


The sequential flow of control is as follows: 


1. The application invokes ITAP| SendsSMS() 


2. The handset begins the process of sending the SMS message out 


3. The notification function specified by pfn is invoked with the status of the message 


delivery 


Associated with this process, the application may receive EVT APP SUSPEND and 
EVT APP RESUME events sometime after step 1. 


Prototype: 


int ITAPI SendSMS 


( 


ITAPI *pITapi, 


co 
co 





AE 





nst char * pszDst, 
nst char * pszMsg, 
ECLSID clsDst, 








PENSMSSTATUS pÊfn, 
void *pUser 


) 


Parameters: 


plTapi 
pszDst 


pszMsg 


cisiD 


Pointer to the ITAPI Interface object 

Number or email ID of the destination where message must be sent to. 
If this is set to NULL and if clsDst is non-zero, this function sends the 
EVT APP MESSAGE event to the application (clsDst) on the local 
handset and the dwParam of that event shall contain pszMsg. In this 
case, the return value of the function is the same as the return value of 
ISHELL SendEvent(). The notification function will not be called since 
this is a local delivery of the message. 

Text message to be sentto the destination mobile. If this is setto NULL, 
the function returns EBADPARM 

If non-zero, it specifies the class ID of the BREW applicaiton on the 
destination mobile to which this message must be sent 
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pfn Notification function that is invoked to inform the status of the SMS 
message sent 

pUser User data to be sent to the notification function 
Examples: 


ITAPI SendSMS (pITapi, "8581112222", "Hello World", 
O, MyMOSMSNotify, pMe ); 





ITAPI SendSMS ( pITapi, "foofêsample.com", "Hello 
World", O, MyMOSMSNotify, pMe ); 


Return Value: 


SUCCESS, if successful. After the message is sent to the other handset, the 
notification function is invoked with the status. The status passed to the notification 
function can be SUCCESS or EFAILED. 


EITEMBUSY, if the device is busy and cannot send this SMS. Generally, a SMS 
message cannot be sent if the notification function has not yet been called for a 
previously sent SMS message. 


EBADPARM, if pszMsg is NULL or pszDst and clsDst are both set to NULL. 
EBADCLASS, if TAPI is not enabled on this handset. 

EFAILED, if there is a general failure in sending the SMS. 

Examples: 


ITAPI SendSMS (pITapi, "8581112222", "Hello World", 0, 
MyMOSMSNotify, pMe); 








ITAPI SendsSMS (pITapi, "foofsample.com", "Hello 
World", 0, MyMOSMSNotify, pMe) ; 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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A text control enables the device user to enter a string of text using the keys on the device. 
The text control consists of an optional title and a rectangular window containing one or more 
lines in which the entered text is displayed to the device user. The text control handles the 
translation of device user key presses into characters. Your application only needs to pass 
keypress events to the text control while it is active and retrieve the text from the control when 
device user text entry has completed. The translation process depends on the text entry 
modes the device supports (for example, the standard multi-tap mode in which the device user 
selects ffom the characters mapped to each key, and Tegic's T9 predictive text input mode). If 
more than one text entry mode is supported, your application makes it possible for the device 
user to select the specified mode while the text control is active. The text control allows you to 
specify a Soft Key menu that is used for this purpose. While the text control is active, your 
application must send all keypress events to it by calling ITEXTCTL HandleEvent(). 


Text controls support the following properties, that can be set with ITEXTCTL SetProperties() 
(the property names are the names of the bit-mask constants used to set and test the property 
values): 


* TP MULTILINE allows multiple lines of text to appear in the text entry window (by 
default, only a single line appears). 


* TP FRAME draws a frame around the text control. 


* TP FIXSETRECT, if set, the actual height more closely represents requested 
height. 


Text controls provide several functions in addition to those in the IControl Interface. 
ITEXTCTL SetTitle() and ITEXTCTL SetText() specify values for the control's title and for the 
text string that appears in the text entry window (the latter function can be used to provide an 
initial value for the window's contents that the device user can edit). ITEXTCTL GetText() 
retrieves the current value of the control's text string and copies it into a buffer. 

ITEXTCTL GetTextPtr() is similar, except that it returns a pointer to the character string in the 
text control that is used to store the text, without making a copy ofit. TEXTCTL SetMaxSize() 
determines the maximum number of characters that can be entered into the text control. 
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ITEXTCTL SetSoftkeyMenu() associates a Soft Key menu control with the text control. This 
is typically a Soft Key menu that you have created and that appears on the screen while the 
text control is displayed. ITEXTCTL SetSoftKkeyMenu() adds an item to the Soft Key menu 
that allows the device user to change the text entry mode (the text string for this item indicates 
the currently selected mode). When it receives this command, the text control displays a menu 
allowing the device user to select the new text entry mode. After the device user selects the 
new mode, the text control is reactivated and the device user continues entering text. While 
entering text, the device user can press the SELECT key to leave text-edit mode and activate 
the Soft Key menu. While the Soft Key menu is active, the device user can press the UP key 
to return to edit mode without making a menu selection. 


To use a text control in your application 


1. 
2. 


Call ISHELL Createlnstance() to create an instance of the text control. 


Call ITEXTCTL SetRect() to specify the screen rectangle that contains the text 
control. 


If specified, call ITEXTCTL SetTitle() or ITEXTCTL SetText() to specify the 
control's title and the initial value of its text string. 


Call ITEXTCTL SetProperties() to set any text control properties. 


Call ITEXTCTL SetSoftkeyMenu() to specify the Soft Key menu that is associated 
with the text control, if any. 


Call ITEXTCTL SetActive() to activate the text control and draw its contents on the 
screen. 


While the text control is active, call ITEXTCTL HandleEvent() to pass it any key 
events generated by the user. 


When the device user has completed entering text, call ITEXTCTL GetText() or 
ITEXTCTL GetTextPtr() to retrieve the text the device user has entered. (Ifyou are 
using a Soft Key menu, the device user may signal the completion of text entry with 
a “Done” item in the menu, or by pressing the SELECT or other key if no Soft Key 
menu is present). 


Call ITEXTCTL Release() to free the text control when you no longer need it. 


List of Header files to be included 


The following header file is required for ITextCtl 


AEEText.h 
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List of functions 


Functions in this interface include: 


ITEXTCTL AddRef() 
ITEXTCTL EnumModelnit() 
ITEXTCTL EnumNextMode() 
ITEXTCTL GetCursorPos() 
ITEXTCTL GetinputMode() 
ITEXTCTL GetProperties() 
ITEXTCTL GetRect() 
ITEXTCTL GetText() 
ITEXTCTL GetTextPtr() 
ITEXTCTL HandleEvent() 
ITEXTCTL IsActive() 
ITEXTCTL Redraw() 
ITEXTCTL Release() 
ITEXTCTL Reset() 
ITEXTCTL SetActive() 
ITEXTCTL SetCursorPos() 
ITEXTCTL SetlnputMode() 
ITEXTCTL SetMaxSize() 
ITEXTCTL SetProperties() 
ITEXTCTL SetRect() 
ITEXTCTL SetSoftkeyMenu() 
ITEXTCTL SetText() 
ITEXTCTL SetTitle() 


The remainder of this section provides details for each function. 
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ITEXTCTL AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
ITEXTCTL Release() 
Return to the List of functions 
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ITEXTCTL. EnumModelnit() 


Description: 
This function initializes the mode enumeration mechanism for the test control. Any time 
you want to enumerate the text control, this function must be called first. 


Prototype: 

void ITEXTCTL EnumbModelnit(lTextCtl * plTextCtl) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL EnumNextMode() 


Description: 
This function is called to enumerate the text control modes. 


Prototype: 
AEEText InputMode ITEXTCTIL EnumNextMode 


( 
ITextCtl * pITextCtl, 
AEEText InputModeInfo * pmInfo 


) 






































Parameters: 
plTextCtl Pointer to the ITextCtl Interface object 
pminfo Optional pointer to receive Text Mode Information. If you do not wish to 


receive this information, call this function with a NULL value as the 
second parameter. 


Return Value: 
An enum of type AEE TextinputMode to indicate the next input mode. 
If the enumeration is complete AEE TM NONE will be returned. 


Comments: 
None 


See Also: 
AEETextinputMode 
Return to the List of functions 
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ITEXTCTL GetCursorPos() 


Description: 
This function gets the position of a cursor in a text control object. 





Prototype: 

int32 ITEXTCTL GetCursorPos (ITextCtl * pITextCt1) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object 


Return Value: 
Absolute position of cursor in text control 


Comments: 
None 


See Also: 
ITEXTCTL SetCursorPos() 
Return to the List of functions 
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ITEXTCTL GetinputMode() 


Description: 
This function allows the caller to get the selected text input mode and the string 
associated with it. 


Prototype: 


AEEText InputMode ITEXTCTIL Get InputMode 
( 
ITextCtl *pITextCtl, 

AEEText InputModeInfo * pmInfo 

) 
































Parameters: 
plTextCtl [in] Pointer to the ITextCtl Interface object 
pminfo [in/out] Input: a pointer to a AEE TextinputModelnfo Info structure to 


be filled OR can be NULL, so as to not fill a structure and 
retum current mode. 


Output: If a valid pointer is given it is filled with the current 
mode and the string associated with that mode. 


Return Value: 
An enum of type AEE TextinputModelnfo to indicate the input mode set. 


Comments: 


fa AEETextinputModelnfo pointer is given the tmMode field, it will match the retum 
value of this function. The pminfo field is not required if the callee is just checking the 
AEE TextinputModelnfo and does not need the string associated with it. 


See Also: 
AEE TextinputModelnfo 
Return to the List of functions 
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ITEXTCTL GetProperties() 


Description: 
This function returns the text control-specific properties or flags. 


Prototype: 


uint32 ITEXTCTL GetProperties(ITextCtl * pITextCt1) 





Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 


Return Value: 
32-bit properties for the text control. 
Following properties are returned by the text control object: 
TP MULTILINE, if set, text control object is multiple line control. 
TP FRAME, if set, text control object has a frame. 
TP T9 MODE, if set, text control object is in T9 mode. 


TP FIXSETRECT, if set, the actual height more closely represents requested 
height. 


Comments: 
None 


See Also: 
ITEXTCTL SetProperties() 
Return to the List of functions 
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ITEXTCTL GetRect() 


Description: 

This function fills given pointer to AEERect with the coordinates of the current bounding 

rectangle size only for text, not title. This is particularly useful after a control is created 

to determine its optimal/default size and position. 

NOTE: 
lfthe property TP FIXSETRECT is set, this function fills the AEERect with the 
actual bounding rectangle of the control, which is not necessarily the rectangle 
passed in ITEXTCTL SetRect(). 
Ifthe property TP FIXSETRECT is NOT set, this function returns the rectangle that 
was passed in to ITEXTCTL SetRect(). 

















Prototype: 

void ITEXTCTL GetRect (ITextCtl * pITextCtl, AEERect * prc) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object. 

prc Rectangle to be filled with the coordinates of the text control object. 


Return Value: 
None 


Comments: 
None 


See Also: 
AEERect 
ITEXTCTL SetRect() 
Return to the List of functions 
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ITEXTCTL GetText() 


Description: 
This function is used to read text associated with the ITextCtl Interface object in the 
given buffer subject to the maximum of nMaxChars. 


Prototype: 
boolean ITEXTCTL GetText 
( 
ITextCtl * pITextCtl, 
AECHAR * pBuffer, 
unsigned int nMaxChars 


) 








Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 
pBuffer Placeholder for the text. 


nMaxChars | Maximum number of characters to be read. 


Return Value: 
TRUE, if successful. 
FALSE, if unsuccessful. 


Comments: 
None 


See Also: 
ITEXTCTL GetTextPtr() 
Return to the List of functions 
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ITEXTCTL GetTextPtr() 


Description: 
It returns the pointer to the text maintained by the ITextCtl object. The difference 
between this function and GetText is that latter copies the content to a destination 
buffer, and the former just returns the pointer to the text inside the ITextCtl object. 








Prototype: 

AECHAR * ITEXTCTL GetTextPtr(ITextCtl * pITextCtl) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object. 


Return Value: 
Pointer to the text buffer of the test control object 


Comments: 
None 


See Also: 
ITEXTCTL GetText() 
Return to the List of functions 
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ITEXTCTL HandleEvent() 


Description: 
This function is used to handle the events received by text control object. If the text 
control object is in non edit mode, it processes only set title, set text, and the pressing 
the UP and DOWN key events. In text edit mode, it processes various events like key 
up, key down, key held, set title, set text, command event from the soft key menu. 


Prototype: 
boolean ITEXTCTI HandleEvent 


( 
ITextCtl * pITextCtl, 


























ABEEEvent evt, 
uintl6 wp, 
uint32 dwp 
) 
Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 
evt Event code. 
wp 16-bit event data. 
dwp 32-bit event data. 


Return Value: 
TRUE, if the event was processed by the text control. 
FALSE, if otherwise. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL IsActive() 


Description: 
This function returns the active state of the text control object. 


Prototype: 


boolean ITEXTCTL IsActive(ITextCtl * pITextCt1) 





Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 


Return Value: 
TRUE, if the text control is active. 
FALSE, if otherwise. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL, Redraw() 


Description: 
This function instructs the text control object to redraw its contents. The ITextCtl 
Interface object does not redraw its contents every time the underlying data behind the 
text control changes. This allows several data updates to occur while minimizing 
screen flashes. For example, several changes can be made to the contents of the text 
control object with no visible effect until ITEXTCTL Redraw() function is called. 


Prototype: 


boolean ITEXTCTL Redraw(ITextCtl * pITextCtl1) 





Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 


Return Value: 
TRUE, if the text control was redrawn. 
FALSE, if otherwise. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
ITEXTCTL AddRef() 
Return to the List of functions 


417 


Erevi ITextCtl Interface 


ITEXTCTL Reset() 


Description: 
This function instructs the text control to reset (free/delete) its contents and to 
immediately leave active/focus mode. 


Prototype: 


void ITEXTCTL Reset (ITextCtl * pITextCt1) 





Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 


Return Value: 
None 


Comments: 
None 


See Also: 
ITEXTCTL SetActive() 
Return to the List of functions 
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ITEXTCTL SetActive() 


Description: 


This function is used to make a text control object active. Only an active text control 
object handles the event sent to it. Inactive text control object just ignores the events. 
Also an inactive text control object does not draw its frame. 


Prototype: 


void ITEXTCTL SetActive(ITextCt1l * pITextCt1l, boolean bActive) 





Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 
bActive Boolean flag that specifies: 
TRUE: to activate the text control object. 
FALSE: to deactivate the text control object. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL SetCursorPos() 


Description: 


This function is used to set the position of a cursor in a text control object. You can use 
the following defines for nOffset to place the text at the start or end. 





Prototype: 

void ITEXTCTL SetCursorPos (ITextCtl * pITextCtl, int32 nOffset) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object 

nOfíset Placement of the text object 


TC CURSOREND - Place the cursor at the end of the text. 
TC CURSORSTART - Place the cursor at the beginning of the text. 


Return Value: 
None 


Comments: 
If nOffset is < O the cursor is placed at the beginning of the text. 
If nOffset is > the Length of the text, the cursor is placed at the end of the text 


See Also: 
ITEXTCTL GetCursorPos() 
Return to the List of functions 
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ITEXTCTL SetinputMode() 


Description: 
This function allows the caller to set the selected text input mode. 


Prototype: 


AEEText InputMode ITEXTCTIL Set InputMode 
( 
ITextCtl * pITextCtl, 

AEEText InputMode wMode 

) 





























Parameters: 


plTextCtl Pointer to the ITextCtl Interface object. 
wMode Text input mode. 


Return Value: 
An enum of type AEE TextinputMode to indicate the input mode set. 


Comments: 
None 


See Also: 
AEETextinputMode 
Return to the List of functions 
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ITEXTCTL SetMaxSize() 


Description: 
This function is used to set the maximum text size supported by the text control object. 
If the size being set is more than the size already set, this leads to the freeing up of the 
memory associated with the previous size and allocation of the memory per the new 
size. 


Prototype: 


void ITEXTCTIL SetMaxSize (ITextCtl * pITextCtl, uint1l6 nMaxSize) 





Parameters: 


plTextCtl Pointer to the ITextCtl Interface object. 
nMaxSize | Maximum text size in AECHAR characters excluding NULL and if O 
(zero) then no effect. 


Return Value: 
None 


Comments: 


The implementation of this function may vary between devices. Some devices may 
allow text to be entered beyond the maximum size set by this function. 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL SetProperties() 


Description: 
This function sets text control-specific properties or flags. 





Prototype: 

void ITEXTCTL SetProperties(ITextCtl * pITextCtl, uint32 dwProps) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object. 


dwProps 32-bit set of flags/properties. 


Following properties are used for text control object: 
TP MULTILINE, if set, text control object is multiple line control. 
TP FRAME, if set, text control object has a frame. 
TP T9 MODE, if set, text control object is in T9 mode. 


TP FIXSETRECT, if set, the actual height more closely represents requested 
height. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


It deactivates the text control. 


See Also: 
ITEXTCTL GetProperties() 
Return to the List of functions 
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ITEXTCTL SetRect() 


Description: 
This function fills the AEERect data structure with the coordinates of the current 
bounding rectangle to determining the size of the text, not the title. This is particularly 
useful after a control is created to determine its optimal/default size and position. 
NOTE: 
lfthe property TP FIXSETRECT is set, this function fills the AEERect data structure 
with the actual bounding rectangle of the control, which may not be the rectangle set 
using ITEXTCTL SetRect(). 


lfthe property TP FIXSETRECT is NOT set, this function returns the AEERect data 
structure which contains the coordinates of rectangle set using ITEXTCTL SetRect(). 


Prototype: 


void ITEXTCTIL SetRect (ITextCtl * pITextCt1l, const AEERect * prc) 

















Parameters: 


plTextCtl Pointer to the ITextCtl Interface object. 
pre Bounding rectangle for the text control object. 


Return Value: 
None 


Comments: 


By default, the control rectangle of the text control object has a device screen width as 
width and (device screen height - text height) as height starting from the upper left 
corner. 


See Also: 
AEERect 
ITEXTCTL GetRect() 
Return to the List of functions 
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ITEXTCTL SetSoftkeyMenu() 


Description: 
This function replaces the existing Soft Key menu of the text control object with the 
specified menu control object. 





Prototype: 

void ITEXTCTL SetSoftkKeyMenu (ITextCtl * pITextCt1l, IMenuCtl * pm) 
Parameters: 

plTextCtl Pointer to the ITextCtl Interface object. 

pm New menu control object for the soft key menu. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


IMenuCtl's reference count is bumped up and a new menu item is added to the menu 
if an entry mode string is maintained by the text manager. 


See Also: 
None 
Return to the List of functions 
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ITEXTCTL SetText() 


Description: 
This function is used to assign given string as text of the text control object. 


Prototype: 


boolean ITEXTCTL SetText 
( 
ITextCtl * pITextCtl1, 
const AECHAR * psz, 








int cch 
) 
Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 
psz Text string to be set. 
cch Number of AECHAR characters to be assigned from the string to the text 


of the text control object. If cch is negative or greater than the length of 
psz string, then the length of string is used. 


Return Value 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 


426 


Erevi ITextCtl Interface 


ITEXTCTL SetTitle() 


Description: 
This function is used to set title of a text control object. If pText is not NULL, it sets the 
string specified by pText as the title of the text control object. If pText is NULL, it reads 
title string corresponding to the given resource identifier ftom resource file and sets it 
as the title of the text control object. 


Prototype: 
boolean ITEXTCTL SetTitle 

( 
ITextCtl * pITextCtl, 
const char * pszResFile, 
uint16 wResID, 

AECHAR * pText 

) 








Parameters: 
plTextCtl Pointer to the ITextCtl Interface object. 
pszResFile File containing resource string. 
wReslD Resource identifier. 
pText NULL-terminated title string. 


Return Value: 
TRUE, if successful. 
FALSE, if otherwise. 


Comments: 
None 


Side Effects: 
If pText is NULL and pszResFile, WReslD are valid, this function assigns the text 
control object title string to pText. 


See Also: 
None 
Return to the List of functions 
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ITransform, like IBitmap, provides functions for accessing a bitmap. This interface provides 
functions for doing blits with transformations. It supports two kinds of transformation simple 
(with ITRANSFORM TransformBltSimple()) and arbitrary Affine Transforms (with 
ITRANSFORM TransformBitComplex()). 


Unlike many BREW interfaces, ITransform cannot be obtained through 

ISHELL Createlnstance(). Instead, it may be obtained through the Querylnterface method of 
a bitmap object that supports it. For instance, if you had an IBitmap Interface to a bitmap 
object, you would call IBITMAP QuerylInterface() with the class ID AEECLSID TRANSFORM. 


Not all bitmap implementations support ITransform. 

List of Header files to be included 

The following header file is required: 
AEETransform.h 

List of functions 

Functions in this interface include: 


ITRANSFORM AddRef() 
ITRANSFORM Querylnterface() 
ITRANSFORM Release() 
ITRANSFORM TransformBltComplex() 
ITRANSFORM TransformBlitSimple() 


The remainder of this section provides details for each function. 
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ITRANSFORM AddRef() 


Description: 
This function is inherited ffom IBASE AddRef(). 


See Also: 
ITRANSFORM Release() 
Return to the List of functions 
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ITRANSFORM Querylnterface() 


Description: 


This function retrieves a pointer to an interface conforming to the definition of the 
specified class ID. This can be used to query for extended functionality, like future 
versions or proprietary features. Upon a successful query, the interface is returned with 
an incremented instance. The caller is responsible for calling Release() at some point 
in the future. One exception is when the pointer returned is not an interface pointer. In 
that case, the memory will share the lifetime of the object being queried, and the 
returned pointer will not be used to free or release the object. 


Prototype: 
int ITRANSFORM QueryInterface(ITransform *plTransform, AEECLSID id, void **p); 
Parameters: 
plTransform [in] Pointer to ITransform interface. 
id [in] A globally unique id to identify the entity (interface or data) that we 
are trying to query. 
p [out] Pointer to the data or interface that we want to retrieve. Ifthe value 
passed back is NULL, the interface or data that we query are not 
available. 


Return Value: 
SUCCESS, if successful. 
Error code, if otherwise. 


Comments: 


On failure, *p should be set to NULL, but it is good form to explicitly set *p to NULL 
before calling QuerylInterface(). 


See Also: 
[Transform Properties 
Return to the List of functions 
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ITRANSFORM Release() 


Description: 
This function is inherited from IBASE Release(). 


See Also: 
ITRANSFORM AddRef() 
Return to the List of functions 
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ITRANSFORM TransformBltComplex() 


Description: 


This function blits a one bitmap to another, applying a set of arbitrary Affine 
transformations. 


Prototype: 


int ITRANSFORM TransformBltComplex 


( 
IT 


int 


in 
IB 
in 
in 
un 


ransform *pITransform, 
xDst, 

t yDst, 

itmap *pSrc, 

Lt xSrc, 

E- YSLC, 

signed dxSrc, 


unsigned dySrc, 


co 
ui 


) 


Parameters: 








plTransform 
xDst, yDst 


pSrc 


xSrc, ySrc 
dxSrc, dySrc 
pMatrixTransform Pointer to AEE TransformMatrix structure that specifies the 


unComposite 


Return Value 


nst AE 








ETransformMatrix *pMatrixTransform, 





nt8 unComposite 


Pointer to the ITransform interface of the destination bitmap 


Coordinate in destination where upper left corner of source will be 
drawn. This assumes that no transform is being applied. The 
location is specified by the center of the source area, which is 
drawn at (xDst + dxSrc / 2, yDst + dySrc / 2). 


Source bitmap. The bitmap types supported for pSrc vary from 
implementation to implementation, but when pSrc is of the same 
type as the destination bitmap, support is guaranteed. 

Upper left corner of source bitmap to be blitted to destination. 
Width and height of source bitmap area to be blitted. 


transformation to be used. 
See ITransform Properties. 


SUCCESS, if successful. 
EUNSUPPORTED, if blit is not supported. 


Comments: 
None 


See Also: 


ITRANSFORM TransformBlitSimple() 
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AEETransformMatrix 


ITransform Properties 
Return to the List of functions 
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ITRANSFORM TransformBltSimple() 


Description: 


This function blits a one bitmap to another, applying a set of simple, predefined 
transformations. 


Prototype: 


int ITRANSFORM TransformBltSimple 


( 
IT 


int 


in 
IB 
in 
in 
un 
un 
ui 
ui 


ransform *pITransform, 
xDst, 

t yDst, 

itmap *pSrc, 

Lt xSrc, 

E- VSEE, 

signed dxSrc, 

signed dySrc, 

nt16 unTransform, 

nt8 unComposite) 





Parameters: 

plTransform Pointer to the ITransform interface of the destination bitmap 

xDst, yDst Coordinate in destination where upper left corner of source will 
be drawn. This assumes that no transform is being applied. The 
location is specified by the center of the source area, which is 
drawn at 
(xDst + dxSrc / 2, yDst + dySrc / 2). 

pSrc Source bitmap. The bitmap types supported for pSrc vary from 
implementation to implementation, but when pSrc is of the same 
type as the destination bitmap, support is guaranteed. 

xSrc, ySrc Upper left corner of source bitmap to be blitted to destination. 

dxSrc, dySrc Width and height of source bitmap area to be blitted. 

unTransform Set of flags that specify transformation to perform. See 
ITransform Properties. 

unComposite See ITransform Properties. 


Return Value 


SUCCESS, if successful. 
EUNSUPPORTED, if blit is not supported. 


Comments: 
None 


See Also: 


ITRANSFORM TransformBltComplex() 
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[Transform Properties 
Return to the List of functions 
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This section describes the Application Execution Environment (AEE) functions that must be 
called by the OEM layer, and the required/preferred call sequences. 


List of functions 


Functions in this interface include: 


AEE Active() 

AEE Autolnstall() 

AEE BuildPath() 

AEE CheckPtr() 

AEE CheckStack() 

AEE CreateControl() 

AEE Dispatch() 

AEE EnumRegHandlers() 
AEE Event() 

AEE Exception() 

AEE Exit() 

AEE FreeMemory() 

AEE GetAppContext() 
AEE GetClassinfo() 

AEE GetShell() 

AEE Init() 

AEE Isinitialized() 

AEE IsTestDevice() 

AEE Key() 

AEE KeyHeld() 

AEE KeyPress() 

AEE KeyRelease() 

AEE LinkSysObject() 
AEE NetEventOccurred() 
AEE RegisterForDataService() 
AEE RegisterForValidTime() 
AEE Resume() 

AEE ResumeEx() 

AEE SetAppContext() 
AEE SetEventHandler() 
AEE SetSysTimer() 

AEE SocketEventOccurred() 
AEE Suspend() 

AEE TimerExpired() 
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The remainder of this section provides details for each function. 
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AEE Active() 


Description: 
This function can be called by the OEM layer to determine the ClassID of the active 
applet or control in the AEE. It returns O (Zero) if there is no active applet. The function 
is provided primarily for key handling so that the OEM layer can determine whether 


keypad events must be passed to the AEE or handled by the existing user interface 
(UI). 


Prototype: 


AEECLSID AEE Active (void) 




















Parameters: 
None 


Return Value: 
AEECLSID of the active applet or control. 
O (zero) if there is no active applet. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE Autolnstall() 


Description: 


This function allows the OEM to automatically install an item on the device. The 
function performs the following tasks: 


* Scans the device to see if the specified item is already installed. 


* Ifthe specified item is not installed, displays a “Configuring Appls...” pop-up 
window. 


* Queries the ADS for information about the item and downloads it. 
* Runs the first application listed for the item. 




















Prototype: 

int AEE AutoInstall (DLITEMID id, DLPRICEID idPrice) 
Parameters: 

id ADS/BDS item identifier. 


idPrice ' ADS/BDS price handle. If O (zero), uses the subscription or purchase handle. 


Return Value: 
EALREADYLOADED if the specified application is already installed. 
SUCCESS if the application has been run to download the selected item. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE. BuildPath() 


Description: 


This function constructs a fully qualified file path based on the substring passed to the 
function. It also determines whether the path is in the AEE shared directory. 


Prototype: 


const char * AEE BuildPath 
( 
IShell * po, 
const char * pszSub, 
char * pszDest, 
uintl6 * pwDirType 
) 











Parameters: 
po Pointer to the ISHELL interface. 
pszSub Input path substring. 
pszDest Final output path string. 


pwDirType Flag that notes whether the path is in the AEE shared directory. 


Return Value: 
Final output path string. 
NULL if the input path is NULL or the length exceeds MAX FILE NAME. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE CheckPtr() 


Description: 
This function validates a chunk of memory. It checks for one of the following conditions: 
* Memory is non-NULL. 
* Memory is in valid range. 
* Memory is not in heap. 
* Memory update will not overwrite/overread a heap node. 


Prototype: 


boolean AEE CheckPtr 
( 
const char * pszFunc, 
void * pMem, 
uint32 nsize, 
boolean bWrite 


) 











Parameters: 
pszFunc Pointer to string detailing the exception if an exception occurs. 
pMem Memory buffer. 
dwSize Size in bytes. 
bWrite Pointer is writeable memory or not. 


Return Value: 
TRUE ifitis a valid pointer. 
FALSE otherwise. 


Comments: 
If the pointer is in RAM but not in the heap, this function returns TRUE. 
Sends the following exceptions: 
AEE EXCEPTION MEMPTR, if the pointer is bad. 


AEE EXCEPTION HEAP, if the pointer is in the heap, but would overread or 
overwrite a heap node 


See Also: 
None 
Return to the List of functions 
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AEE CheckStack() 


Description: 
This function checks whether a stack overflow has occurred. 


Prototype: 


void AEE CheckStack (const char * pszFunc) 














Parameters: 


pszFunc Pointer to the string detailing the exception if an exception occurs. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE CreateControl() 


Description: 


This function allows the OEM layer to create user interface controls for use by the 
existing user interface (UI), if one is provided. 



































Prototype: 

int AEE CreateControl (OEMCONTEXT pdc, AEECLSID iid, vold ** po) 
Parameters: 

pdc Pointer to OEMCONTEXT for the display. 

jid Class of the control. 

po Destination pointer to be filled. 


Return Value: 
O (zero) if successful. 


Comments: 
None 


See Also: 
ISHELL Createlnstance() (See the BREW AP! Reference Guide.) 
Return to the List of functions 
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AEE Dispatch() 


Description: 


This function must be called by the OEM layer whenever the AEE signal has been 
detected within the thread where the AEE. Init() call was made. The function performs 
the following tasks: 


* Checks the status of any pending BREW Resume function and calls it. 
* Checks to see if any BREW-related timers have expired. 


Prototype: 


uint32 AEE Dispatch (void) 














Parameters: 
None 


Return Value: 
AEE DISPATCH TIMERS PENDING, if BREW has active short-term timers pending 
AEE DISPATCH CALLBACKS PENDING, if BREW has active callbacks pending 
AEE DISPATCH THROTTLING if BREW, if is consuming too much time - throttling 
O(zero), if BREW has no high-priority callbacks or timers pending. 


Comments: 
None 


See Also: 
AEE Init() 
AEE Exit() 
Return to the List of functions 
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AEE EnumRegHandlers() 


Description: 
This helper function provides OEMs with the ability to: 
- Enumerate handlers for a specified type/mime type; 
- Enumerate all handlers for a specified handler type; 
- Enumerate all handlers for all types; 
Example: 


static void EnumTest (Me * pMe) 





EEClassInfo ci; 

ECHAR szName [32]; 

EMSET (&ci,0,sizeof (AEEHandlerInfo)); 

i.pszAppName = szName; 

i.nNameSize = sizeof (szName) ; 

E EnumRegHandlers (pMe, AEECLSID APP, "application/foo", 
EnumCB, pMe, &ci); 





























= oq SPrpD- 





























) 
static boolean EnumCB (void * pcxt, AEECLSID clsType, const char * 
pszMime, AEECLSID cls, AEEClassInfo * pci) 

t 

Me * pMe = (void *)pcxt; 

AddToMyMenu (pMe, pci); 

return (TRUE) ; 

) 
















































































Prototype: 
int AEE EnumRegHandlers 
( 
AEECLSID clsType, 
const char * pszMimeType, 
PFNREGCB pfn 
,rvoid * pUser, 
AEEClassInfo * pci 
) 
Parameters: 
clsType Type of handlers (example: AEECLSID APP, AEECLSID VIEW, etc.) 
pszMimeType Mime type or extension 
pfn Pointer to callback for each entry 
pUser User data pointer for callback 
pci Pointer to AEEClassinfo structure to fill for each entry 


Return Value: 
O on SUCCESS 


445 


Erevi OEM AEE Interface 


Comments: 
Enumeration will stop if handler returns FALSE 


See Also: 
None 
Return to the List of functions 
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AEE. Event() 


Description: 


This function sends an event to the active BREW application. It is equivalent to calling 
ISHELL SendEvent(), and reduces the complexity of the OEM layers. 





























Prototype: 

boolean AFE Event (AEEEvent evt, uintl6 wParam, uint32 dwParam) 
Parameters: 

evt AEE Event code. 

wParam Extra parameter (16 bits). 


dwParam | Extra parameter (32 bits). 


Return Value: 
TRUE if the event is handled. 
FALSE if the event is ignored. 


Comments: 
None 


See Also: 
AEE KeyPress() 
AEE KeyRelease() 
AEE Key() 
AEE KeyHeld() 
Return to the List of functions 


447 


= OEM AEE Interface 


AEE Exception() 


Description: 


This function allows the OEM to send exceptions under special conditions. This causes 
the following to occur: 


* An immediate jump from the current context back to the root of the dispatcher (or 
message pump). 


* Areport of the error in a modal form (timer-based pause). 
* Termination of the offending BREW application. 


Prototype: 


void AEE Exception (const char * pszFunc, AFEEExceptionType e) 
































Parameters: 


pszFunc Pointer to string detailing the exception. 
e Exception type. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE Exit() 
Description: 
This function closes the AEE. It must be called to effectively close the BREW layers. 
The function performs the following tasks: 
* Unloads any active applications or modules. 
* Frees any memory used by the AEE. 
* Releases any open files used by the AEE. 
* Releases the SMS layer if the AEE had opened it. 
This function must be called by the OEM layer to close the AEE. 
Prototype: 
void AEE Exit (void) 
Parameters: 


None 


Return Value: 
None 


Comments: 
None 


See Also: 
AEE Init() 
Return to the List of functions 
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AEE FreeMemory() 


Description: 


This function can be called by the OEM layer when RAM resources reach a critical low 
level. In this case, the AEE attempts to free any unused RAM. 


Prototype: 


void AEE FreeMemory (uint32 nNeeded) 











Parameters: 
nNeeded Required RAM. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE GetAppContext() 


Description: 
This function gets the current application context. 


Prototype: 


void * AEE GetAppContext (void) 














Parameters: 
None 


Return Value: 
Pointer to the current application context. 


Comments: 
None 


See Also: 
AEE SetAppContext() 
Return to the List of functions 
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AEE GetClassinfo() 


Description: 


This helper function is provided for OEMs to gain easy access to extended information 
regarding BREW classes. Although the data can be obtained through the use of other 
interfaces (ISHELL QueryClass and IDOWNLOAD), this function is provided for more 
ready access to these parameters. 


Prototype: 


int AEE GetClassInfo (AEECLSID cls, AEEClassInfo * phi) 





























Parameters: 
None?? 


Return Value: 
O on SUCCESS 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE GetShell() 


Description: 


This function returns the IShell interface pointer to the active AEE shell. This pointer 
can then be used by the OEM layer to invoke any other ISHELL interface function. 


Prototype: 


IShell * AEE GetShell (void) 











Parameters: 
None 


Return Value: 
Pointer to the shell interface. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE. Init() 


Description: 


This function initializes the AEE. During initialization, the AEE performs the following 
tasks: 


* Builds the list of loaded modules (static and dynamic). 
* Initializes a timer if an alarm has been set. 

* Initializes any pending notification objects. 

* Initializes the SMS layer if available. 


The AEE passes the operating system signal to the AEE. Init() function when 
AEE Dispatch() must be called. The OEM layer must call AEE Dispatch() during user 
interface (UI) initialization before making any other AEE calls. 


Prototype: 


IShell * AEE Init (uint32 dwAEESig) 























Parameters: 
dwAÃEESig Operating system signal that is reserved for use by the AEE. 


Return Value: 
Pointer to the AEE shell object. 


Comments: 
None 


See Also: 
AEE Exit() 
Return to the List of functions 
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AEE lIslnitialized() 


Description: 
This function checks whether BREW has been initialized. 


Prototype: 


boolean AEE IsInitialized(void) 














Parameters: 
None 


Return Value: 
TRUE if initialized. 
FALSE otherwise. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 


455 


= OEM AEE Interface 


AEE IsTestDevice() 


Description: 
This function checks whether the device is a test device. 


Prototype: 


boolean AEE IsTestDevice (void) 














Parameters: 
None 


Return Value: 
TRUE ifitis a test device. 
FALSE otherwise. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE Key() 


Description: 


This function sends a key event to the AEE. Itis important as most BREW applications 
only process EVT KEY events generated by this call. 


Prototype: 


boolean AEE Key (AVKType key) 











Parameters: 
key ' BREW keycode (AEEVCodes.h). 


Return Value: 
TRUE if the event is handled. 
FALSE if the event is ignored. 


Comments: 
None 


See Also: 
AEE KeyPress() 
AEE KeyRelease() 
AEE KeyHeld() 
Return to the List of functions 
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AEE KeyHeld() 


Description: 


This function sends a key held eventto the AEE. Itis up to the OEM layer to determine 
when a key is held. 


Prototype: 


boolean AEE KeyHeld(AVKType key) 











Parameters: 
key ' BREW keycode (AEEVCodes.h). 


Return Value: 
TRUE if the event is handled. 
FALSE if the event is ignored. 


Comments: 
None 


See Also: 
AEE KeyPress() 
AEE KeyRelease() 
AEE Key() 
Return to the List of functions 
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AEE KeyPress() 


Description: 
This function sends a key press event to the AEE. 


Prototype: 


boolean AEE KeyPress (AVKType key) 














Parameters: 
key ' BREW keycode (AEEVCodes.h). 


Return Value: 
TRUE if the key press is handled. 
FALSE if the key press is ignored. 


Comments: 


Most BREW applications ignore this event. Itis provided for games and other 
complicated applications. 


See Also: 
AEE KeyRelease() 
AEE Key() 
AEE KeyHeld() 
Return to the List of functions 
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AEE KeyRelease() 


Description: 
This function sends a key release event to the AEE. 


Prototype: 


boolean AEE KeyRelease (AVKType key) 














Parameters: 
key ' BREW keycode (AEEVCodes.h). 


Return Value: 
TRUE if the event is handled. 
FALSE if the event is ignored. 


Comments: 


Most BREW applications ignore this event. Itis provided for games and other 
complicated applications. 


See Also: 
AEE KeyPress() 
AEE Key() 
AEE KeyHeld() 
Return to the List of functions 
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AEE LinkSysObject() 


Description: 


This function associates an AEESysObject with the currently running application, if 
any. It's designed to help clean up "system" resources when an application exits. It's 
intended use is for the AEESysObject to be embedded in the implementing interface 























object. 
Prototype: 

int AEE LinkSysObject (AEESysObject *pso) 
Parameters: 

pso the object to be associated with the application 


Return Value: 
SUCCESS, if the operaion was successful. 


EALREADY, if pso->pac is already set, and pac is a valid application, call 
AEE UnlinkSysObject first 


Comments: 
None 


Side Effects: 


pso->pac is updated to the application with which the object is associated 


See Also: 
AEESysObject 
Return to the List of functions 
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AEE NetEventOccurred() 


Description: 


This function is the network and socket callback function. it is called when there is any 
activity with the network/sockets. This is the callback function invoked by the 
OEMSocket layer. The address is passed to it during the initialization of the network 
layer. 


Prototype: 


void AEE NetEventOccurred (void) 

















Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE RegisterForDataService() 


Description: 


This function allows the OEM layer to take advantage of the BREW notification 
capability to monitor the system for data service. 


Prototype: 





void AEE RegisterForDataService 





( 
PEFNNOTIFY pfn, 
void * pData, 
boolean bActive 


) 





Parameters: 
pfn Function to call when the data service is determined. 
pData Callback argument for the data service. 


bActive Callback is only to be called when there is data service and the first BREW 


application has started. 


Return Value: 


None 


Comments: 


None 


See Also: 


PFNNOTIFY 
Return to the List of functions 
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AEE RegisterForValidTime() 


Description: 


This function allows the OEM layer to take advantage of the BREW notification 
capability to monitor the system for valid time. 


Prototype: 


void AEE RegisterForValidTime 
( 
PEFNNOTIFY pfn, 
void * pUser, 
boolean bActive 


) 











Parameters: 


pfn Function to call when the valid time is determined. 
pUser Callback argument for the valid time. 


bActive ' Callback is only to be called when the time is valid and the first BREW 
application has started. 


Return Value: 
None 


Comments: 
None 


See Also: 
PFNNOTIFY 
Return to the List of functions 
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AEE Resume() 


Description: 


This function allows the OEM layer to restart the BREW application that was 
suspended using AEE Suspend(). This is equivalent to calling 
ISHELL SendEvent(EVT APP RESUME), which restarts the suspended application. 


This function simplifies the reactivation of any BREW application that was suspended 
by the user interface (UI). 


Prototype: 


boolean AEE Resume (void) 














Parameters: 
None 


Return Value: 
TRUE if the event is successfully processed. 
FALSE if the event is not processed. 


Comments: 
None 


See Also: 
AEE ResumeEx() 
AEE Suspend() 
Return to the List of functions 
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AEE ResumeEx() 


Description: 


This function is provided for the OEM to use when developing custom objects that 
require inter-thread notifications. It posts the AEECallback in the BREW system 
resume queue. 


This is the same mechanism used by the BREW standard SoundPlayer interface. In 
that case, a callback is issued from another thread, the resume callback is posted, and 
the API is then called back in the UI thread's context. 


Prototype: 


void AE 














Parameters: 


pcb 
wFlags 


pa 


Return Value: 
None 


Comments: 
None 


See Also: 

















E ResumeEx (AEECallback * pcb, uint1l6 wFlags, void * pa) 


Pointer to the callback 

Flags for the callback: 
AEE RESUME CB SYS: This flag tells the BREW layer to associate 
the callback with the system rather than the currently active application. 
This is done to support callbacks that may need to be called when 
applications are not running or across applications. 
AEE RESUME CB PRIO: This flag instructs BREW to place this 
callback ahead of other callbacks. 

Pointer to the application context. 


AEE Resume() 
Return to the List of functions 
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AEE SetAppContext() 


Description: 
This function sets the application context. 


Prototype: 


void * AEE SetAppContext (void * pc) 














Parameters: 


pc Pointer to the new application context. 


Return Value: 
Pointer to the previous application context. 


Comments: 
None 


See Also: 
AEE GetAppContext() 
Return to the List of functions 
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AEE SetEventHandler() 


Description: 


This function allows an OEM layer to create and use AEE controls from outside AEE 
applets. The callback is called whenever the control or AEE issues an event. 


Prototype: 


void AEE SetEventHandler (void * pData, AEEHANDLER pfn) 





























Parameters: 


pData Private data that is passed as the first parameter to the callback. 
pfn Private callback function that is to be called by the AEE. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE SetSysTimer() 


Description: 
This function allows the OEM layer to set a short-term timer. Upon expiration, the 
specified callback function is called, passing it the specified user data pointer as its first 
argument. Note the following: 
* The timer will expire at Current Time + <Milliseconds specified>. 
* Any normal processing can be done in the callback. This includes drawing to the 
screen, writing to files, and so on. 
* Timers do not repeat. The OEMs must reset the timer if they want a repeating 
timer. 
* Specifying the same callback/data pointers automatically overrides a pending 
timer with the same callback/data pointers. 














Prototype: 
int AEE SetSysTimer (int32 nMSecs, PFEFNNOTIFY pfn, void * pUser) 
Parameters: 
nMSecs Timer expiration in milliseconds. The expiration will occur at Current Time 
+ dwMSecs. 
pfn The callback that will be called when the timer expires. 
pUser The data pointer that will be passed as the only parameter to the callback. 


Return Value: 
EBADPARM if an invalid time or callback is specified. 
ENOMEMORY if memory allocation fails. 
O (zero) if successful. 


Comments: 
None 


See Also: 
PFNNOTIFY 
Return to the List of functions 
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AEE SocketEventOccurred() 


Description: 


This function is the network and socket callback function. It is called when there is any 
activity with the network and sockets. This callback function is invoked by the 
processor's network layer. The address is passed to it during the initialization of the 
network layer. 


Prototype: 


void AEE SocketEventOccurred (void) 














Parameters: 
None 


Return Value: 
None 


Comments: 
None 
Return to the List of functions 
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AEE Suspend() 


Description: 


This function allows the OEM layer to suspend the active BREW application. Itis 
equivalentto calling ISHELL SendEvent(EVT APP SUSPEND). The application can 
be restarted by calling AEE Resume(). 


This function simplifies the suspension of any AEE activity during times when the user 
interface (UI) is active. 


Prototype: 


void AEE Suspend (void) 














Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
AEE Resume() 
Return to the List of functions 


471 


= OEM AEE Interface 


AEE TimerExpired() 


Description: 


This function adds an event to the event queue that will cause AEE DISPATCH to be 
called. 


Prototype: 


void AEE TimerExpired (void) 














Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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AEE UnlinkSysObject() 


Description: 
This function de-associates an AEESysObject with an application. 


























Prototype: 

int AEE UnlinkSysObject (AEESysObject *pso) 
Parameters: 

pso the object to be associated with the application 


Return Value: 
SUCCESS, if the operaion was successful. 
EALREADY, if pso->pac is NULL, i.e. not associated with an app 


Comments: 
None 


Side Effects: 
pso->pac is set to NULL. 


See Also: 
AEESysObject 
Return to the List of functions 
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OEM Address Book Interface 


This section describes the Address Book Interface functions that the AEE uses to implement 
the Address Book functionality. Prior to 2.0 release these were independent function. They 
have been converted into an interface 


List of functions 


Functions in this interface include: 


OEMAddr EnumNextRec() 
OEMAddr EnumRecinit() 
OEMAddr GetCatCount() 
OEMAddr GetCatList() 
OEMAddr GetFieldinfo() 
OEMAddr GetFieldinfoCount() 
OEMAddr GetNumRecs() 
OEMAddr RecordAdd() 
OEMAddr RecordDelete() 
OEMAddr RecordGetByID() 
OEMAddr RecordUpdate() 
OEMAddr RemoveAllRecs() 
OEMAddrBook CommonExit() 
OEMAddrBook Commoninit() 
OEMAddrBook Exit() 
OEMAddrBook Init() 


The remainder of this section provides details for each function. 
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OEMAddr EnumNextRec() 


Description: 


This function returns the information about the next record based on the search criteria 
specified in most recent call to OEMAddr EnumReclnit(). 


Prototype: 


uint16 OEMAddr EnumNextRec 











( 

AFEAddrCat * cat, 
AEEAddrField ** ppItems, 
* nItemCount, 

















int * pErr 
) 
Parameters: 
cat On return, if the next record was found, contains the address category 
of that next record. 
ppitems On return, ifthe next record was found, contains the list of address fields 


found in that next record. 


nitemCount On return, if the next record was found, contains the number of address 
fields found in that next record. 


*pErr On return, contains the error code if an error occurred. 


Return Value: 


The recordlD if the next record is successfully found. This function also fills up the 
incoming parameters with the contents of the newly found record. 


AEE ADDR RECID NULL ifthe end of the enumeration has been reached or no 
more records are found. This value must be returned. 


Comments: 


When the end of the enumeration has been reached, the index must not be reset to 
point to the beginning of the enumeration. All subsequent calls to this function must 
continue to return AEE ADDR RECID NULL. The caller must call 

OEMAddr EnumRecinit() to re-initialize the search criteria. 


See Also: 
OEMAddr EnumRecinit() 
Return to the List of functions 
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OEMAddr EnumRecinit() 


Description: 


This function searches the address book for specific records, and also sequentially 
retrieves all of the records in the database. The function initializes the enumeration of 
records in the address book based on a specific search criteria. When enumeration 
has been initialized, the function OEMAddr EnumNextRec() is used to iterate through 
the records that match this search criteria. 


Prototype: 


int OEMAddr EnumRecInit 





( 














AEEAddrCat wlCategory, 








AFEAddrFieldID wFieldID, 
void * pData, 
uint16 wDataSize 





) 


Parameters: 
wCategory 


wFieldID 


pData 


wDataSize 


Return Value: 


Category type to be matched. Ilfsetto AEE ADDR CAT NONE, itis 
ignored. 

AEEAddrFieldID to be matched. Ifsetto AEE ADDRFIELD NONE, it 
is ignored. Typically, OEMs do not allow searching for records on this 
field ID (for example, searching for records based on EMAIL may not be 
allowed). In this case, return EFAILED and 

IADDRBOOK EnumNextFieldsInfo(). 

If non-null, the actual data that must be matched. If NULL, it is ignored. 
For example, if wFieldlD is setto AEE ADDRFIELD NAME, pData 
contains the actual name to be matched. 

Size of pData. 


AEE SUCCESS if enumeration is successfully initialized. 
EFAILED if fails. 


Comments: 


This function can also be used to enumerate all records in the database by specifying 
AEE ADDR CAT NONE for the category parameter and AEE ADDRFIELD NONE 
for the field parameter. 


See Also: 


OEMAddr EnumNextRec() 
Return to the List of functions 
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OEMAddr GetCatCount() 


Description: 


This function returns the number of address categories supported by the address 
book. Examples of address categories are PERSONAL and BUSINESS. Each record 
in the address book can belong to a specific address category. If the concept of 
categories are not supported in the address book, this function must return O (zero). 


Prototype: 


int OEMAddr GetCatCount (void) 





Parameters: 
None 


Return Value: 
Number of categories supported. 


Comments: 


Itis valid to return O (zero) from this function if the address book does not support the 
concept of categories for each record. 


See Also: 
None 
Return to the List of functions 
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OEMAddr GetCatList() 


Description: 


This function returns information about all of the address categories supported by the 
address book in the device. The function is called only if OEMAddr GetCatCount() 
returned a value other than O (zero). 

















Prototype: 
int OEMAddr GetCatList (AEEAddrCat *p, int nSize) 
Parameters: 
p Pointer allocated by the caller that can hold information about the address 


categories. 
nSize Number of AEEAddrCat elements that can fit into the array pointed to by p. 


Return Value: 


AEE SUCCESS if successful. Even if nSize is less than the total number of categories 
supported, this function must return AEE SUCCESS as long as nSize is greater than 
O (zero). 

EFAILED if fails. 


Comments: 


The categories must be converted from the OEM Iist to the AEE values before 
returning. A list of pre-defined AEEAddressCategories is in AEEAddrBook.h. You can 
also add your own categories. 


See Also: 
None 
Return to the List of functions 
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OEMAddr GetFieldInfo() 


Description: 


This function returns detailed information about each field type supported for the given 
category. This function is typically called after the OEMAddr GetFieldinfoCount() 
function. 


Prototype: 


int OEMAddr GetGetFieldInfo 








AFEAddrCat c, 
AEEAddrFieldInfo * pf, 
int nSize 

















Parameters: 
c Address category for which the field information is to be returned. 
pf Pointer to an array of AEEAddrFieldInfo structures (allocated by the caller) 


where information is to be returned by this function. 
nSize Number of AEE AddrFieldInfo elements that can fit into the array pointed to 
by pf. 


Return Value: 


AEE SUCCESS if successful. Even if nSize is less than the total number of categories 
supported, this function must return AEE SUCCESS as long as nSize is greater than 
O (zero). 

EFAILED if fails. 


Comments: 


The AEEAddrFieldinfo structure contains detailed information about the fields, such as 
FieldID, and the maximum number of fields of this ID supported in each record. 
Detailed information about this structure is in AEEAddrBook.h and the BREW AP! 
Reference Guide. 


See Also: 
None 
Return to the List of functions 
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OEMAddr GetFieldInfoCount() 


Description: 
This function returns the number of types of fields supported for the given category. If 
the concept of categories is not supported, the function may return the total number of 
types of fields supported for each record in the address book. Examples of fields are 
NAME, WORK NUM, FAX NUM, URL, and ADDRESS. 

















Prototype: 
int OEMAddr GetFieldInfoCount (AEEAddrCat c) 
Parameters: 
c Address category whose number of supported field types is to be returned. 


Return Value: 
Number of types of fields supported for the given address category, 
O (zero) if category is not supported. 


Comments: 
None 


See Also: 
OEMAddr GetFieldInfo() 
Return to the List of functions 
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OEMAddr GetNumRecs() 


Description: 
This function returns the total number of records found in the address book. 


Prototype: 


uint16 OEMAddr GetNumRecs (void) 





Parameters: 
None 


Return Value: 
Count of the total number of records currently found in the address book. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMAddr RecordAdd() 


Description: 


This function adds a new record to the address book. The fields to be added to this 
record are passed as parameters to this function. 


Prototype: 


uint16 OEMAddr RecordAdd 








( 
ABEAddrCat cat, 
AEEAddrField * pItems, 

















int nItemCount, 
int * pErr 
) 
Parameters: 
cat Address category to which this record belongs. Ifthe concept categories 
is not supported, this parameter can be ignored. 
pltems Pointer to an array of items that must be added to the record. Each item 


contains information such as FieldlD, DataType, Data, and DataLength. 


NOTE: For detailed information about this structure, see the 
AEEAddrBook.h or BREW API Reference Guide. 


nitemCount Number of fields in this record. It also indicates that the array pltems 
contains this number of fields. 


pErr If an error occurs, the error code must be placed in this pointer before 
retuming from this function. You must check for this parameter being 
NULL before storing the error value in it. 


Return Value: 


The recordID if successful. This function must retum the record ID of the newly added 
record. 


AEE ADDR RECID NULL if fails. The parameter *pErr must contain the error code. 
A list of error codes is in AEEError.h. This value must be returned. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMAddr RecordDelete() 


Description: 
This function deletes a specified record from the address book. 


Prototype: 


int OEMAddr RecordDelete (uint16 recID) 





Parameters: 


recilD | IDofthe record to be deleted from the address book. 


Return Value: 
AEE SUCCESS if record is successfuly deleted. 
EFAILED if fails. 


Comments: 


When deleting a record while enumerating through the list of addressbook records, 
care should be taken that the next enumeration returns the correct record. 


See Also: 
None 
Return to the List of functions 
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OEMAddr RecordGetBylID() 


Description: 


This function retrieves the information about a specified record, and returns 
information about all of the fields in this record. This function does not delete the record 
from the address book. 


Prototype: 


int OEMAddr RecordGetByID 

( 

uint16 recID, 

AEEAddrCat * cat, 
AEEAddrField ** ppItems, 
int * nItemCount, 
int * pErr 


) 


























Parameters: 
reclD ID of the record whose fields are to be retrieved and returned 
cat On input, this is a valid pointer to AEEAddrCat. On return, this pointer 
points to the address category to which the record belongs. 
ppltems Pointer for passing info about the fields. While implementing this 


function, the OEMs must allocate memory for *ppltems using the 
function MALLOC(). This memory is freed by the caller (BREW). 

nltemCount On input, this is a valid pointer to an integer. On return, this pointer 
contains the count of the number of fields present in this record, and 
indicates that the array *ppltems contains this number of fields on 
return. 


pErr If any error occurs, the error code must be placed into this pointer 
before returning from this function. You must check for this parameter 
being NULL before storing the error value in it. 


Return Value: 
AEE SUCCESS if the record information is successfully retrieved. 
EFAILED if fails. The parameter *pErr must contain the exact error code. 


Comments: 


Memory for *ppltems must be allocated by the implementer of this function. This 
memory is released by the caller. 


See Also: 
None 
Return to the List of functions 
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OEMAddr RecordUpdate() 


Description: 


This function updates all of the fields in the specified record. It replaces all existing 
fields in that record with the fields being passed to this function. 


Prototype: 


int OEMAddr RecordUpdate 

( 

uint16 recID, 
ABEAddrCat cat, 
AEEAddrField * pItems, 


























int nItemCount, 
int * pErr 
) 
Parameters: 
reciD ID of the record whose fields are to be updated. 
cat Address category to which this record belongs. If the concept of 
categories is not supported, this parameter can be ignored. 
pltems Pointer to an array of items that are to be added to the record. Each item 


contains information such as FieldlD, DataType, Data, and DataLength. 


NOTE: For detailed information about this structure, see the 
AEEAddrBook.h or BREW AP! Reference Guide. 


nltemCount Number of fields in this record. It also indicates that the array pltems 
contains this number of fields. 


pErr If an error occurs, the error code must be placed in this pointer before 
returning from this function. You must check for this parameter being 
NULL before storing the error value in it. 


Return Value: 
AEE SUCCESS if the record is successfully deleted. 
EFAILED if fails. 


Comments: 


This function is similar to OEMAddr RecordAdd(); the main difference is that this 
function updates all of the fields in an existing record, while OEMAddr RecordAdd() 
adds a new record to the address book. 


See Also: 
OEMAddr RecordAdd() 
Return to the List of functions 
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OEMAddr RemoveAllRecs() 


Description: 
This function deletes all records from the address book. 


Prototype: 


int OEMAddr RemoveAlIRecs (void) 





Parameters: 
None 


Return Value: 
AEE SUCCESS if all the records are successfully deleted. 
EFAILED if fails. 
EUNSUPPORTED if this function is not supported. 


Comments: 


Since this is a sensitive operation, you can decide not to support it. If this function is 
not supported, the value EUNSUPPORTED must be returned from this function. 


See Also: 
None 
Return to the List of functions 
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OEMAddrBook CommonExit() 


Description: 


This function is called when the BREW AddressBook interface is deleted, allowing 
OEMs to free the OEM layer object. 


Prototype: 


IOEMAddrBook *0OEMAddrBook CommonExit 

( 
AEECLSID ClsId, IOEMAddrBook *pme 
) 


























Parameters: 
Clsld Used to designate the OEM layer media used for address book 
storage. 
pme pointer to the IOEMAddrBook object to be deleted. 


Return Value: 
This function retums NULL. 


Comments: 


If any memory was allocated during the call to OEMAddrBook Commontlnit() this 
function should be used to free it. This function can also be used for any media/device 
cleanup that needs to occur when the object is released. 


See Also: 
OEMAddrBook Commoninit() 
Return to the List of functions 
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OEMAddrBook Commontinit() 


Description: 


This function is called when the BREW AddressBook interface is created. It allocates 
memory for the OEM address book object and populates the object with the 
appropriate OEM functions depending on the input class ID. 


This allows OEMs to customize the AddressBook OEM layer for specific storage 




















media. 
Prototype: 

IOEMAddrBook *0OEMAddrBook CommonInit (AEECLSID ClsId); 
Parameters: 

Clsld Used to designate the OEM layer media used for address 


book storage. 


Return Value: 
Returns a pointer to the IOEMAddrBook object for any valid class ID. 
Otherwise, returns NULL. 


Comments: 


OEMs can add support for new media/devices and class IDs by adding the new class 
ID to the switch statement in this function, allocating memory for the object, and 
initializing the object with the appropriate OEM functions. 


See Also: 
None 
Return to the List of functions 
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OEMAddrBook. Exit() 


Description: 


This function is called when the BREW AddressBook interface is deleted, allowing the 
address book to be cleaned up. 


Prototype: 


void OEMAddrBook Exit (void) 











Parameters: 
None 


Return Value: 
None 


Comments: 


If any memory has been allocated during the address book operation, this is the time 
to free it. 


See Also: 
None 
Return to the List of functions 
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OEMAddrBook Init() 


Description: 


This function is called when the BREW AddressBook interface is created, allowing the 
address book to be initialized. 


Prototype: 


boolean OEMAddrBook Init (void) 





Parameters: 
None 


Return Value: 
TRUE if initialization is successful. 
FALSE if initialization fails. 


Comments: 


If this function returns FALSE, BREW does not allow the IAddrBook interface to be 
created, and therefore does not allow access to the OEM Address Book. 


See Also: 
None 
Return to the List of functions 
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This section describes the Application Interface functions that are required by the AEE. 
Reference implementations of some of the functions are provided. See the OEM Porting Guide 
for details on reference implementations. 


List of functions 


Functions in this interface include: 


OEM AuthorizeDownload() 
OEM CheckPrivacy() 

OEM GetltemStyle() 

OEM LockMem() 

OEM Notify() 

OEM SimpleBeep() 

OEM UnlockMem() 


The remainder of this section provides details for each function. 
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OEM AuthorizeDownload() 


Description: 
This function is called before each download. A callback must be sent before the 
IDOWNLOAD Acquire() operation is completed. The IDownload class instance and 
the item/price IDs are used to query information about the item. The IDownload pointer 
is used to set the HTTP headers sent to the ADS. This is performed with the 
CSetHeaders method, which uses the following parameters: 


pUser: User data to be passed to the callback. 

ID: tem ID. 

iPrice: Item Price Handle. 

pltem: Pointer to information structure for the item. 

nErr: Error code. If non-zero, the download aborts and this error is reported. 


Prototype: 


void OEM AuthorizeDownload 


( 
IDownload * pd, 
DLITEMID iID, 
DLPRICEID iPrice, 
DLItem * pItem, 
PEFNCHECKDLCB pfn, 
void * pUser 


) 














Parameter(s): 
pd Pointer to the IDownload instance. 
ID Item ID. 
iPrice Item price ID. 
pltem Pointer to the information structure for the item. 
pfn Callback function. 
pUser User data to be passed to the callback. 


Return Value: 


None 


Comments: 


None 


See Also: 
None 


Return to the List of functions 
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OEM CheckPrivacy() 


Description: 
This function allows the OEM/Carrier to specify the correct action for various outbound 
requests. The OEM/Carrier can modify this function to conform to the requirements for 
the Carrier, allowing the OEM to display a message or prompt to the user, such as 
“Contact the network.” 


Prototype: 
void OEM CheckPrivacy 
( 





OEMPrivacyRegType t, 
AEECallback *pCB, 
int *pStatus; 

) 














Parameters: 
t Privacy request type (PRT POSITION or PRT DIAL VOICE). 
pCB Pointer to AEECallback structure. Refer to AEECallback structure 
pStatus Return value 


O (zero) if successful 
EFAILED if invalid request type 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM GetltemStyle() 


This function retrieves information regarding the drawing style for stock objects. BREW 
can use a default set of values if none are provided by this function. To use the default 
values, return FALSE to this function. 


The default values used by BREW are: 


bBigX = di.cxScreen >= 120; 



















































































bBigY = di.cyScreen >= 120; 

switch (nColorDepth) ( 

case 1: 
pNormal->ft = AEE FT NONE; 
pSel->ft = AEE FT NONE; 
pNormal->rolImage = AEE RO COPY; 
pSel->roImage = AEE RO NOT; 
break; 

case 2: 
pNormal->ft = AEE FT EMPTY, 
pSel->ft = AEE FT BOX; 
pNormal->rolImage = AEE RO COPY; 
pSel->roImage = AEE RO COPY; 
break; 

default: 


if (bBigX && bBigy) ( 


















































pNormal->ft = AEE FT 3D EMPTY; 
pSel->ft = AEE FT RAISED; 
y else ( 
pNormal->ft = AEE FT EMPTY; 
pSel->ft = AEE FT BOX; 
) 
pNormal->rolImage = AEE RO MASK; 
pSel->roImage = AEE RO MASK; 











break; 


) 


pSel->xOffset = pNormal->xOffset = bBigX ? 3 : 1; 
pSel->yOffset pNormal->yOffset bBigY ? 3 : 1; 








Prototype: 


boolean OEM GetItemStyle 








T 





EltemType t, 
EltemStyle * pNormal, 
EltemStyle * pSel 











T 














-PpPp- 


Parameters: 
t Item type. 
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pNormal Normal style 
pSel Selected style 


Return Value: 
None 


Comments: 
Return FALSE for BREW to pick the default values. 


See Also: 
None 
Return to the List of functions 
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OEM LockMem() 


Description: 
NOTE: This function should not be used without clearly understanding all rules 
associated with handled-based memory. 
By default, all memory allocated via the BREW heap is locked and cannot be relocated. 
This function provides a means for the caller to specify that a recently allocated and 
unlocked block is now locked and cannot be moved. 
Initial Allocation: 


pme->m ptr = OEM Malloc (100); 
OEM UnlockMem (&pme->m ptr); 





Use: 
OEM LockMem (&pme->m ptr); 
Perform Work... 

OEM UnlockMem (&pme->m ptr); 





As indicated, this function accepts a pointer to a handle of allocated memory. The 
function will then mark the block as unavailable to be moved in memory. This function 
also increments a "lock count" on the memory block. This allows the caller to pair 
OEM LockMem and OEM UnlockMem inside sub-routines that may be called while 
the memory is locked. In such cases, the memory will not actually be "unlocked" until 
the reference count reaches 0. 


Prototype: 
int OEM LockMem(void ** ppHandle); 


Parameters: 
None. 


Return Value: 
O - Incremented lock count of the memory 
O - Invalid ppHandle 


Comments: 
None 


See Also: 
OEM UnlockMem() 
Return to the List of functions 
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OEM Notify() 


Description: 
This function is called by BREW to notify the OEM about critical system functions. 
These situations include the following: 

OEMNTF APP START 


A query to determine if the specified application can be started. The class ID of the 
application is specified in the dwParam. The OEM should not refuse to start apps unless 
they are in very critical conditions on the device (i.e. incoming call, etc.). In such cases, 
there is no automatic way to start this app at a later time. 


OEMNTF ACTIVATE 


Notification to the OEM that the BREW layer is activating an application. Subsequent 
application start notifications that occur while a previous BREW application is running will 
not be preceded by this notification. 


OEMNTF IDLE 


Notification to the OEM that the BREW layer is closing the last active application in the 
stack of currently active BREW applications. This situation does not mean that all BREW 
applications are closed, but rather that control is retuming to the native UI. 


OEMNTF RESET 

A request by BREW to reset the device. 
OEMNTF CLOSE FILE 

BREW is requesting that a file be closed. 
OEMNTF SHOW CALL DIALOGS 


Indicates whether the OEM should show call dialogs. If dwParam is TRUE, the OEM 
should show these dialogs. If it is FALSE, the OEM should not show them. This call is 
typically made only by the network layer to inhibit/re-enable the display of call status dialogs 
during PPP sessions. 


OEMNTF GET CONTEXT 
This call is made by BREW when the OEM starts a BREW app. This notification is required 


because in these cases OEMNTF ACTIVATE is not called. The dwParam is of type 
OEMAppState. 


OEMNTF APP EVENT 


This notification is sent to the OEM layer for any app event <= EVT APP LAST EVENT. 
This can be used by OEMs to track when an app is being started, suspended, resumed or 
stopped. The passed structure contains all of the elements of the event passed to the app. 


NOTE: No OEM modification of the parameters is supported. The OEM should NOT alter the 
parameters. The app context of the target app has been asserted when this notification is 
made. Any calls to BREW will appear to come from the app. Moreover, access to system 
functions, etc. will be limited based upon the rights of the app. The dwParam is of type 
OEMAppEvent. This structure is as follows: 
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typedef struct | OEMAppEvent 





( 


LT] 


ECLSID cls: 








ClassID of the app to which the event is being 





sent. 

AELEvent evt: 
uint1i6 wp: 
uint32 dwp: 
EMAppEvent; 





Eri 

















+ o 











Prototype: 











Event Code of the event being sent to the app 
wParam of the event being sent to the app 
dwParam of the event being sent to the app. 








int OEM Notify (OEMNotifyEvent evt, uint32 dwParam) 


Parameters: 


evt The event code. 
dwParam Context sensitive data. 


Return Value: 
O (zero) if successful. 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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OEM SimpleBeep() 


Description: 


This function plays a standard OEM beep tone and vibration given the duration, and 
returns TRUE if successful. 


Prototype: 


boolean OEM SimpleBeep (BeepType nBeepType, boolean bLoud) 











Parameters: 


nBeepType Beep type that can be one of the following: 
BEEP OFF: stop playback of the current beep or vibration 
BEEP ALERT: alert beep tone 
BEEP REMINDER: reminder beep tone 
BEEP MSG: message beep tone 
BEEP ERROR: error beep tone 
BEEP VIBRATE ALERT: alert vibration 
BEEP VIBRATE REMIND: reminder vibration 
bLoud Boolean flag that sets the playback volume high or low. 


Return Value: 
TRUE if successfuly played or stopped the tone or vibration. 
FALSE otherwise. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 


499 


Eri OEM Application Interface 


OEM UnlockMem() 


Description: 
NOTE: This function should not be used without clearly understanding all rules 
associated with handled-based memory. 
By default, all memory allocated via the BREW heap is locked and cannot be relocated. 
This function provides a means for the caller to specify that a recently allocated 
memory block can be moved. It is called as follows: 
Initial Allocation: 


pme->m ptr = OEM Malloc (100); 
OEM UnlockMem (&pme->m ptr); 





Use: 
OEM LockMem (&pme->m ptr); 
Perform Work... 

OEM UnlockMem (&pme->m ptr); 





As indicated, this function accepts a pointer to a handle of allocated memory. The 
function will then mark the block as available to be moved in memory. This function 
monitors a "lock count" on the memory block. This allows the caller to pair 

OEM LockMem and OEM UnlockMem inside sub-routines that may be called while 
the memory is locked. In such cases, the memory will not actually be "unlocked" until 
the reference count reaches 0. 


Prototype: 


int OEM UnlockMem (void ** ppHandle); 





Parameters: 
None. 


Return Value: 
O - Decremented lock count of the memory 
Negative Values: 
EALREADY - Memory is already unlocked and associated with another sentinal. 
EMEMPTR - Invalid ppHandle 
EFAILED - Association is invalid. Breakpoint thrown on SDK simulator. 


Comments: 
None 


See Also: 
OEM LockMem() 
Return to the List of functions 
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OEMBTSDP Interface 


This module specifies the functions required for BT SDP support in BREW. There are no 
requirements for supporting calls ffom other DMSS tasks. Itis assumed that only BREW will 
be making calls to this interface. 


List of functions 


Functions in this interface include: 


OEMBTSDP CancelDiscovery() 
OEMBTSDP CloseLib() 
OEMBTSDP DiscoverDevices() 
OEMBTSDP GetDeviceName() 
OEMBTSDP GetServerChannel() 
OEMBTSDP Init() 

OEMBTSDP OpenLib() 
OEMBTSDP Shutdown() 


The remainder of this section provides details for each function. 
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OEMBTSDP CancelDiscovery() 


Description: 


This function cancels the outstanding discovery request. The OEM layer should not 
generate any more events related to device discovery. 


Prototype: 


void OEMBTSDP CancelDiscovery (int32 libhandle) 





Parameters: 
libhandle Library handle for the BT SDP instance. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMBTSDP CloseLib() 


Description: 


This function can be called by BREW at some point after OEMBTSDP OpenLib() to 
close a BT SDP library instance 


Prototype: 


extern void OEMBTSDP CloseLib(int32 lilbhandle) 





Parameters: 
libhandle Valid library handle greater than O (zero). 


Return Value: 
None 


Comments: 


The OEM should not send any events after the close to the Using the Notification 
function for this instance. 


See Also: 
OEMBTSDP OpenLib() 
Return to the List of functions 
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OEMBTSDP DiscoverDevices() 


Description: 


This functions tells the OEM layer to start the discovery process. It should generate 
events on getting the response from the neighboring devices. 


Prototype: 


int32 OEMBTSDP DiscoverDevices 
( 
int32 libhandle, 

OEMBT service class enum type svcclass, 
int32 maxResps 


) 





Parameters: 
libhandle Library Handle for the BT SDP Instance. 
svcclass Service class of the BT device. 


maxResps Max number of responses accepted. 


Return Value: 
OEMBTSDP DISCOVERY INPROGRESS if discovery is already in progress. 
O if successful. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMBTSDP GetDeviceName() 


Description: 


This function requests the OEM layer to send the device name request to the specified 
device. 


Prototype: 


extern int32 OEMBTSDP GetDeviceName 
( 
int32 libhandle, 
OEMBT Addr * ldaddr 
) 








Parameters: 
libhandle Library handle for the BT SDP instance. 
bdaddr BT device address. 


Return Value: 
OEMBTSDP DISCOVERY INPROGRESS if a discovery is already in progress. 
O if successful. 
-1 if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMBTSDP GetServerChannel() 


Description: 


This function requests the OEM layer to send server channel request to the specified 
device and service class 


Prototype: 


int32 OEMBTSDP GetServerChannel 





O 

( 

int32 libhandle, 

OEMBT service class enum type service class 
) 


Parameters: 
libhandle Library handle for the BT SDP instance. 
bdaddr BT device address. 


service class Service class of the device. 


Return Value: 
OEMBTSDP DISCOVERY INPROGRESS if a discovery is already in progress. 
O if successful. 
-1 if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMBTSDP Init() 


Description: 


This function is called by BREW to indicate that it is ready to accept notifications, and 
to specify the function to be called to deliver notifications. It should return 1. Non- 
functional stubs for this API return O to indicate that BT 1/O is unsupported. 


The OEM BT layer uses the function pointer passed by BREW to notify BREW of 
events. When this notification function is called, BREW is responsible for taking care 
of thread safety issues. 


Prototype: 


int 16 OEMSDP Init (PEFNBTISDPNOTIFY pfnNotify) 





Parameters: 


pfnNotify Function to call with notifications. 


Return Value: 
1 if successful (BT SDP is supported). 
O if fails (BT SDP unsupported). 


Comments: 
None 


See Also: 
OEMBTSDP Shutdown() 
Return to the List of functions 
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OEMBTSDP OpenLib() 


Description: 


This function can be called by BREW at some point after OEMBTSDP Init() to open a 
BT SDP Library Instance. 


Prototype: 


extern int32 OEMBTSDP OpenLib() 





Parameters: 
None 


Return Value: 
Valid library handle greater than O (zero). 
<Q in case of error. 


Comments: 
None 


See Also: 
OEMBTSDP CloseLib() 
Return to the List of functions 
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OEMBTSDP Shutdownt() 


Description: 


This function can be called by BREW at some point after OEMBTSIO Init() to indicate 
that the previously-registered notify callback should not be called anymore. 


Prototype: 


void OEMBTSDP Shutdown (void) 





Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
OEMBTSDP Init() 
Return to the List of functions 
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OEMBTSIO Interface 


This section describes the functions required for BT IO support in BREW. There are no 
requirements for supporting calls from other DMSS tasks. It is assumed that only BREW will 
be making calls to this interface. 


This interface currently describes one mode of interaction with one type of device: applet 
Initiated. 


List of functions 


Functions in this interface include: 


OEMBTSIO Close() 
OEMBTSIO DataAvailable() 
OEMBTSIO Init() 
OEMBTSIO Opent() 
OEMBTSIO ProcessEvents() 
OEMBTSIO Read() 
OEMBTSIO Write() 


The remainder of this section provides details for each function. 


S10 


Era OEMBTSIO Interface 


OEMBTSIO Close() 


Description: 


This function can be called by BREW at some point after OEMBTSIO Open() to close 
the specified port. 


Prototype: 


int32 OEMBTSIO Close (int32 portHandle) 





Parameters: 
portHandle Returned by OEMBTSIO Opent(). 


Return Value: 
O(zero) if successful. 
OEMBTSIO INVALID HANDLE ifit is an invalid handle. 


Comments: 
None 


See Also: 
OEMBTSIO Open() 
Return to the List of functions 


SU 


Era OEMBTSIO Interface 


OEMBTSIO DataAvailable() 


Description: 
This function determines if there is data available to be read from the BT port. 


Prototype: 


int32 OEMBTSIO DataAvailable (uint32 portHandle) 





Parameters: 
portHandle 'Retumned by OEMBTSIO Opent(). 


Return Value: 
1 if data is available 
O (zero) if no data is available. 


Comments: 
None 


See Also: 
OEMBTSIO Open() 
Return to the List of functions 
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OEMBTSIO. Init() 


Description: 


This function is called by BREW to indicate that it is ready to accept notifications, and 
to specify the function to be called to deliver notifications. It should return 1. Non- 
functional stubs for this API return O to indicate that BT IO is unsupported. 


The function pointer passed by BREW should be used by the OEM BT layer to notify 
BREW of events. When this notification function is called, BREW is responsible for 
taking care of thread safety issues. 


Prototype: 


int32 OEMBTSIO Init (PEFNBTSIONOTIFY pfnNotify) 





Parameters: 


pfnNotify Function to call with notifications. 


Return Value: 
1 if successful (BT IO is supported). 
O (zero) if fails (BT IO is unsupported). 


Comments: 
None 


See Also: 
OEMBTSIO Close() 
Return to the List of functions 
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OEMBTSIO Opent() 


Description: 


This function can be called by BREW at some point after OEMBTSIO Init() to open a 
BT Port This will not otherwise affect the state of the BT driver or the receive and 
transmit buffers. 


Prototype: 


int32 OEMBTSIO Open (OEMBTConnectionInfo * pCntInfo) 








Parameters: 


pCntinfo Pointer to the connection information. 


Return Value: 
Porthandle identified by an integer. 
OEMBTSIO INVALID HANDLE if fails. 


Comments: 
None 


See Also: 
OEMBTSIO Close() 
Return to the List of functions 


514 


Eri OEMBTSIO Interface 


OEMBTSIO ProcessEvents() 


Description: 
This function processes the events related to Bluetooth Stack. 


Prototype: 


void OEMBTSIO ProcessEvents () 








Parameters: 
None 


Return Value: 
None 


Comments: 
This function should be called in response to the Wakeup Callback 


See Also: 
OEMBTSIO Init() 
Return to the List of functions 
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OEMBTSIO Read() 


Description: 


This function copies data from the receive buffer to the pcBuf[ ] buffer supplied by the 
caller. As much data as is available should be copied, never exceeding nLen bytes and 
never exceeding the number of bytes available in the receive buffer. Data copied to 
pcBuf[ ] should be removed from the receive buffer. 





Prototype: 

int32 OEMBTSIO Read(char * pcBuf, int32 nLen, uint32 nPort) 
Parameters: 

pcBuf Pointer to the character buffer. 


nLen Length of the buffer in bytes. 
nPort Port handle returned by OEMBTSIO Open(). 


Return Value: 
The number of bytes removed from the receive buffer. 


lfthe receive buffer is empty, no bytes should be copied and this function should return 
O (zero). 


If the port is in error, -1 should be returned. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMBTSIO Write() 


Description: 


This function should append nLen bytes from the specified buffer (pcBuf) to the end 
of the transmit buffer. If the buffer cannot accomodate nLen bytes, as many bytes as 
can fit should be appended. 


Prototype: 


int32 OEMBTSIO Write(const char * pcBuf, int32 nLen, uint32 nPort) 





Parameters: 


pcBuf Pointer to the character buffer. 
nLen Length of the buffer in bytes. 
nPort Port handle returned by OEMBTSIO Open(). 


Return Value: 
The number of bytes appended to the transmit buffer. 


If the receive buffer is full, no bytes should be copied and this function should return O 
(zero). 


If the port is error, -1 should be returned. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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This section describes the Configuration Interface functions that are required by the AEE. 


List of functions 


Functions in this interface include: 


OEM GetAddrBookPath() 
OEM GetAppPath() 
OEM GetConfig() 

OEM GetDevicelnfo() 
OEM GetDevicelnfoEx() 
OEM GetLogoPath() 
OEM GetMIFPath() 
OEM GetPath() 

OEM GetRingerPath() 
OEM GetSharedPath() 
OEM SetConfig() 


The remainder of this section provides details for each function. 
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OEM GetAddrBookPath() 


Description: 


This function is called by the AEE to determine the path for the address book 
application and files. The path must not have a trailing directory separation character. 


Prototype: 


const char * OEM GetAddrBookPath (void) 





Parameters: 
None 


Return Value: 
The const char pointer to the path. 


Comments: 
None 


See Also: 
OEM GetPath() 
Return to the List of functions 
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OEM GetAppPath() 


Description: 


This function is called by the AEE to determine the path for the applet directories. The 
path is the directory in which the AppManager looks for the applets. The path must not 
have a trailing directory separation character. 


Prototype: 


const char * OEM GetAppPath (void) 





Parameters: 
None 


Return Value: 
The const char * pointer to the path. 


Comments: 
None 


See Also: 
OEM GetPath() 
Return to the List of functions 
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OEM GetConfig() 

















Description: 
This function retrieves the device configuration information related to the download 
services. 
Prototype: 
int OEM GetConfig (AEEConfigItem i, void * pBuff, int nSize) 
Parameters: 
Item that needs to be retrieved. It can be one of the Configuation 
Parameters 


pBuff Buffer in which the new values are stored. 
nSize Size ofthe buffer. 


See the Configuation Parameters list for the values of the i parameter: 


Return Value: 
O (zero) if successful. 
EBADPARM if size or parameter is not valid 
EUNSUPPORTED if the config item is not supported 
Other implementation-specific error codes 


Comments: 
None 


See Also: 
OEM SetConfig() 
Configuation Parameters 
Return to the List of functions 
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OEM GetDevicelnfo() 


Description: 
This function retrieves the current device's physical and hardware characteristics. 


Prototype: 


void OEM GetDeviceInfo (AEEDeviceInfo * pi) 

















Parameters: 


pi Retrieved buffer where AEEDevicelnfo is stored. See the BREW API Reference 
Guide. 


Return Value: 
None 


Comments: 
None 


See Also: 
AEEDevicelnfo 
Return to the List of functions 
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OEM GetDevicelnfoEx() 


Description: 


This method is used to get specific information about the device. This function takes 
an ID that specifies what information is needed. The buffer contains the corresponding 
information on return. 


Prototype: 


int OEM GetDeviceInfoEx 
( 
AEEDeviceItem nItem, 
void *pBuff, 
int *pnSize 


); 




















Parameters: 
nitem Specifies the Item whose info is needed. Please see documentation of 
AEEDeviceltem for the supported Device Items. 
pBuff Contains the corresponding information on return 
pnSize Contains the size of pBuff. On return, it contains the size filled. This parameter 


maybe NULL for certain device Items. 


Return Value: 
SUCCESS, if successful 
EBADPARM, if bad parameters are passed in 
EUNSUPPORTED, if this item is not supported 


Comments: 
None 


See Also: 
AEEDeviceltem 
Return to the List of functions 
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OEM GetlLogoPath() 


Description: 


This function is called by the AEE to determine the path for the LOGO files. The path 
must not have a trailing directory separation character. 


Prototype: 


const char * OEM GetLogoPath (void) 





Parameters: 
None 


Return Value: 
The const char pointer to the path. 


Comments: 
None 


See Also: 
OEM GetPath() 
Return to the List of functions 
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OEM GetMIFPath() 


Description: 


This function is called by the AEE to determine the path for the MIFs (Module 
Information Files). The path is the directory in which the AppManager looks for MIFs. 
The path must not have a trailing directory separation character. 


Prototype: 


const char * OEM GetMIFPath (void) 





Parameters: 
None 


Return Value: 
Returns const char pointer to path 


Comments: 
None 


See Also: 
OEM GetPath() 
Return to the List of functions 
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OEM GetPath() 


Description: 


This function is called by the AEE to determine the path for the directory names used 
by BREW. Following are the directories: 


* APPS: the directory where all the MIF files and applet directories are stored. 
* SHARED: the directory where all the shared files are stored. 
* RINGER: the directory where all the ringer files are stored. 
* ADDRBOOK: the directory where all of the address book files are stored. 
* MIF: the directory where all of the MIF files are stored. 
* LOGO: the directory where all of the LOGO files are stored. 
The path must not have a trailing directory separation character. 


Prototype: 


const char * OEM GetPath (uint1l6 wType) 





Parameters: 


wType Any of the six directories used by the AEE: APPS, ADDRBOOK, MIF, 
RINGER, SHARED, or LOGO. 


Return Value: 
The const char * pointer to the path. 


Comments: 
None 


See Also: 
OEM GetAddrBookPath() 
OEM GetAppPath() 
OEM GetLogoPath() 
OEM GetMIFPath() 
OEM GetRingerPath() 
OEM GetSharedPath() 
Return to the List of functions 
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OEM GetRingerPath() 


Description: 


This function is called by the AEE to determine the path for the ringer files. The path 
must not have a trailing directory separation character. 


Prototype: 


const char * OEM GetRingerPath (void) 





Parameters: 
None 


Return Value: 
The const char * pointer to the path. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM GetSharedPath() 


Description: 


This function is called by the AEE to determine the path for the shared directory, which 
all applets with the shared directory access privilege share. The path must not have a 
trailing directory separation character. 


Prototype: 


const char * OEM GetSharedPath (void) 





Parameters: 
None 


Return Value: 
The const char * pointer to the path. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM SetConfig() 


Description: 
It sets new handset configuration information related to the download services. 


Prototype: 


int OEM SetConfig (AEEConfigItem i, void * pBuff, int nSize); 

















Parameters: 


Item that needs to be retrieved. It can be one of the Configuation 
Parameters 


pBuff Buffer in which the new values are stored. 
nSize Size ofthe buffer. 


See the Configuation Parameters list for the values of the i parameter: 


Return Value: 
O (zero) if successful. 


Comments: 
None 


See Also: 
OEM GetConfig() 
Configuation Parameters 
Return to the List of functions 
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OEM Cyclic Redundancy 
Check Interface 


This section describes the function for the Cyclic Redundancy Check (CRC) Interface. 


List of functions 


Functions in this interface include: 


OEMCRC 16 step() 


The remainder of this section provides details for each function. 
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OEMCRC 16 step() 


Description: 
This function calculates a step-by-step 16-bit CRC over the specified disjunct data. 
This is more commontly referred to as CCITT-16. Use it to produce a CRC and check 
a CRC. The CRC value passed in is used to continue the CRC calculation from a 
previous call, allowing this routine to be used to CRC discontinuous data. 





Prototype: 

uint16 OEMCRC 16 step (uint1l6 seed, uint8 * buf ptr, uint16 num bytes) 
Parameters: 

seed Initial state of the accumulation register. 

buf ptr Pointer to the buffer containing the bytes to the CRC. 


num bytes Number of bytes in the buffer to calculate the CRC over. 


Return Value: 
The calculated CCITT-16 CRC. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Database Interface 


This section describes the Database Interface functions that the AEE database interface uses. 
OEMs may use the reference implementation provided, or modify and reimplement this 
module. The modified/reimplemented functions must comply with this interface specification. 


List of functions 


Functions in this interface include: 


OEM DBClose() 

OEM DBCreate() 

OEM DBDelete() 

OEM DBFree() 

OEM DBInit() 

OEM DBMakeReadOnly() 
OEM DBOpen() 

OEM DBRecordAdd() 
OEM DBRecordCount() 
OEM DBRecordDelete() 
OEM DBRecordGet() 

OEM DBRecordNext() 
OEM DBRecordUpdate() 


The remainder of this section provides details for each function. 


532 


Eri OEM Database Interface 


OEM DBClose() 


Description: 


This function closes the database specified by pDBContext. As part of closing, the 
memory associated with this database is freed. 


Prototype: 


void OEM DBClose (OEMCONTEXT pDBContext, AEE DBError * pDBErr) 
































Parameters: 


pDBContext Handle of the database to be closed. 


pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
None 


Comments: 
None 


See Also: 
OEM DBOpen() 
Return to the List of functions 
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OEM DBCreate() 


Description: 


This function creates a new database and returns a handle to the created database. If 
wMinRecCount and wMinRecsSize are specified, the function also reserves memory 
for this database. 


Prototype: 


OEMCONTEXT OEM DBCreate 
( 
const char * szDBName, 
word wMinRecCount, 
word wMinRecSize, 

AEE DBError * pDBErr 

) 
































Parameters: 


szDBName Name of the database to be created. 


wMinRecCount | Minimum number of records that this database must support. Itis 
used in conjunction with wMinRecSize to determine the total 
memory to be reserved for the database. If this parameter is O 
(zero), it is ignored. 

wMinRecSize Minimum size of the record. This is used in conjunction with the 
wminRecCount to determine the total memory to be reserved for 
the database. If this parameter is O (zero), it is ignored. 


pDBErr Place holder to contain error code information on return. If NULL, no 
error code is retumed. 


Return Value: 
OEMCONTEXT if successful, this is used as a handle to the newly created database. 
NULL if fails. If pDBErr is non-null, it contains the actual error code on return. 


Comments: 


If szDBName is NULL or an empty string, set the error code to 
AEE DB ERR NOT EXIST and return NULL. 


See Also: 
OEM DBOpen() 
OEM DBDelete() 
Return to the List of functions 
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OEM DBDelete() 


Description: 
This function deletes the database specified by szDB Name. 


Prototype: 


void OEM DBdelete (const char * szDBName, AEE DBError * pDBErr) 























Parameters: 


szDBName ' Name ofthe database to be deleted 


pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
None 


Comments: 


If szDBName is NULL or an empty string, set the error code to 
AEE DB ERR NOT EXIST and return NULL. 


See Also: 
OEM DBCreate() 
Return to the List of functions 
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OEM DBFree() 


Description: 


This function frees the memory allocated for the buffer returned by 
OEM DBRecordGet. 


Prototype: 


void OEM DBFree 
( 














OEMCONTEXT pDBContext, 
byte * pbyRecBuf, 
AE 
) 

















E DBError * pDBErr 





Parameters: 


pDBContext Handle of the database. 
pbyRecBuf Pointer to the previously allocated record buffer that is to be freed. 


pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM DBInit() 


Description: 
This function initializes the database subsystem. 


Prototype: 
int OEM DBInit( void ) 


Parameter(s): 
None 


Return Value: 
If initialization was successfully completed, returns zero. 
In all other cases, returns any non-zero value. 


Comments: 
Routine currently does nothing, but is called by OEM Init 


See Also: 
None 
Return to the List of functions 
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OEM DBMakeReadOnly() 


Description: 


This function makes the specified database file read only. The contents of the index file 
are appended to the end of the database, and the database is marked as read only. No 
add, update, or delete operations are subsequently allowed on the database. 


Prototype: 


void OEM DBMakeReadOnly (const char * szDBName, AEE DBError * pDBErr) 























Parameters: 


szDBName Name of the database to be made read only. 
pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
None 


Comments: 


If szDBName is NULL or an empty string, set the error code to 
AEE DB ERR NOT EXIST and return NULL. 


See Also: 
None 
Return to the List of functions 
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OEM DBOpen() 


Description: 


This function opens a database and returns a handle to the opened database. If the 
database does not exist, the function returns NULL. It does not create the database. 


Prototype: 


OEMCONTEXT OEM DBOpen (const char * szDBName, AEE DBError * pDBErr) 



































Parameters: 


szDBName Name of the database to be opened 


pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
OEMCONTEXT if successful, this is used as the handle to the opened database. 
NULL if fails. If pDBErr is non-null, the actual error code is placed inside pDBErr. 


Comments: 


The database szDBName must exist. Use OEM DBCreate() to create a database and 
open it. 


If szDBName is NULL or an empty string, set the error code to 
AEE DB ERR NOT EXIST and return NULL. 


See Also: 
OEM DBCreate() 
OEM DBClose() 
Return to the List of functions 
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OEM DBRecordAdd( 


Description: 


OEM Database Interface 


) 


This function adds a new record to the specified database. It returns the ID ofthe newly 


added record. 


Prototype: 


int OEM DBRecordAdd 














EMCONTEXT pdb, 











E DBError * pDBI 











( 

O 

c 

word wBufSize, 
AF 

) 


onst byte * pbBuf, 


Err 


Parameters: 
pdb Database handle. 
pbBuf Pointer to the buffer containing data to be stored in the new record. 


wBufSize Size of the buffer pointed to by pbBuf. 


pDBErr Place holder to 


contain error code information on return. If NULL, no error 


code is returned. 


Return Value: 


ID of the newly added record, if successful. 


OEM REC ID NULL if fails. 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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OEM DBRecordCount() 


Description: 
This function returns the number of records in the database specified by pDBContext. 


Prototype: 


word OEM DBRecordCount (OEMCONTEXT pDBContext, AEE DBError * pDBErr) 



































Parameters: 


pDBContext Handle of the database whose record count is required. 


pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
Number of records in the database, if successful. 
O (zero) if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM DBRecordDelete() 


Description: 
This function deletes the specified record from the database. 


Prototype: 


void OEM DBRecordDelete 
( 








OEMCONTEXT pDBContext, 
word wReclId, 
AF 
) 























E DBError * pDBErr 





Parameters: 
pDBContext Handle of the database. 
wRecld ID of the record. 
pDBErr Place holder to contain error code information on return. If NULL no 


error code is returned. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM DBRecordGet() 


Description: 


This function retrieves a specified record from the database. For the given record ID 
(wRecld), the function retrieves the record information and the data associated with 
that record. The record information is returned by the parameter pReclnfo passed to 
this function. The data associated with that record is returned as a byte*. The memory 
for the byte* is allocated from the heap. It is the caller's responsibility to free the 
memory later. 


The function does not remove the record from the database. It returns a copy of the 
information stored in that record. 


Prototype: 


byte* OEM DBRecordGet 

( 

OEMCONTEXT pDBContext, 
word wReclId, 

AEE DBRecInfo * pRecInfo, 
AEE DBError * pDBErr 

) 























Parameters: 
pDBContext Handle of the database whose record is to be retrieved. 
wRecld ID of the record to be retrieved from the database. 
pReclinfo Information about the retrieved record is returned to the caller using the 
AEE DBReclnfo structure. 
pDBErr Place holder to contain error code information on return. If NULL no 


error code is returned. 


Return Value: 
A pointer to the data stored in the specified record, if successful. 
NULL if fails. 


Comments: 


The record returned is a copy of the actual data stored. The memory for this copy is 
allocated from the heap. A subsequent get call frees this memory and reallocates the 
requisite amount from the heap for that operation. Therefore, after each get call, the 
caller must copy the contents of the buffer returned to their own buffer and call 

OEM DBFree(). 


See Also: 
None 
Return to the List of functions 
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OEM DBRecordNext() 


Description: 


This function retrieves the ID of the record next to the given record ID. If the given 
record ID is OEM DB RECID NULL, the function returns the ID of the first record in 
the given database. Itreturns OEM DB RECID NULL ifwCurRecld is the maximum 
record ID in the database. 


Prototype: 





word OEM DBRecordNext 
( 





EMCONT 





EXT pDBContext, 




















Parameters: 


O 

word wCurRecid, 
AF 

) 





E DBError * pDBErr 


pDBContext Handle of the database 

wCurRecld ' Specifies the ID of the current record. The record next to this record is 
retrieved from the database. 

pDBErr Place holder to contain error code information on return. If NULL, no 
error code is returned. 


Return Value: 
ID of the record 


next to the given record ID, if successful. 


OEM DB RECID NULL if fails. 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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OEM DBRecordUpdate() 


Description: 
This function updates the contents of the given record ID. 


Prototype: 


void OEM DBRecordUpdate 











( 

OEMCONTEXT pdb, 

word wRecld, 

const byte * pbBuf, 
word wBufSize, 

ABE DBError * pDBErr 
) 


























Parameters: 
pdb Database handle. 
wRecld ID of the record whose contents are to be updated. 
pbBuf Pointer to the buffer containing updated data to be stored in the given 
record. 
wBufSize Size of the buffer pointed to by pbBuf. 
pDBErr Place holder to contain error code information on return. If NULL, no 


error code is returned. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Debug Interface 


This section describes the functions in the Debug Interface. 
List of functions 
Functions in this interface include: 


OEMDebug Printf() 
OEMDebug VPrintf() 


The remainder of this section provides details for each function. 
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OEMDebug Printf() 


Description: 


This function prints text through a debug mechanism. It is very similar to printf(), but 
returns nothing. 


Prototype: 


void OEMDebug Printf(const char * pszFormat, ...) 





Parameter(s): 


pszFormat A printf-like format string. 
Arguments for printf. 


Return Value: 
None 


Comments: 


This function uses MSG FATAL macros to interface with DMSS debug messages. 
Unfortunately, the MSG macros do not copy the data and do not give an indication 
when they are done with it. 


The function keeps DBG NUM STORES data buffers. If messages are dropped, 
garbled, or mixed together, increase the number of buffers. 


Side Effects: 


Sends messages through msg, put. 


See Also: 
OEMDebug VPrintf() 
Return to the List of functions 
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OEMDebug VPrintf() 


Description: 


This function prints text through a debug mechanism. It is very similar to printf(), but 
returns nothing. 


Prototype: 


void OEMDebug VPrintf (const char * pszFormat, va list ap) 





Parameter(s): 


pszFormat A printf-like format string. 
ap List of arguments. 


Return Value: 
None 


Comments: 


This function uses OEMDebug Printf() to print a string. If the string is too long, memory 
corruption will occur. 


See Also: 
OEMDebug Printf() 
Return to the List of functions 
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OEM Display Interface 


NOTE: This module provides all the basic display routines that AEE files use. OEMs must 
either implement or replace the implementation of these functions. 


This section describes the basic Display Interface functions that the AEE files use. 


List of functions 


Functions in this interface include: 


IOEMDISP Backlight() 
IOEMDISP GetDefaultColor() 
IOEMDISP GetDeviceBitmap() 
IOEMDISP GetPaletteEntry() 
IOEMDISP GetSymbol() 
IOEMDISP GetSystemFont() 
IOEMDISP MapPalette() 
OEMDisp New() 

IOEMDISP SetAnnunciators() 
IOEMDISP SetPaletteEntry() 
IOEMDISP Update() 


The remainder of this section provides details for each function. 
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IOEMDISP Backlight() 


Description: 
The function turns the device backlight on or off. 


Prototype: 


int IOEMDISP Backlight (TIOEMDisp *pMe, boolean bOn) 








Parameters: 


pMe Pointer to the OEM Display Interfacel. 
bOn Flag that determines whether to tum the backlight on or off. 


Return Value: 
SUCCESS is returned if the function performed correctly. 
EUNSUPPORTED if the operation is not supported 
Other implementation-specific error codes 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP GetDefaultColor() 


Description: 
This function is used to query the default system colors. 


Prototype: 


int IOEMDISP GetDefaultColor 
( 





IOEMDisp *pMe, 
AFECIlrItem clr, 
RGBVAL *pRGB 

) 














Parameters: 
pMe [in] Pointer to the OEM Display Interface. 
clr [in] Item for which to obtain color. 


pRGB [out] RGB value of the corresponding color. 


Return Value: 
SUCCESS is returned if the function performed correctly. 
Other implementation-specific error codes 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP GetDeviceBitmap() 


Description: 
This function retrieves an interface to the device (screen) bitmap. 








Prototype: 

int IOEMDISP GetDeviceBitmap (IOEMDisp * pMe, IBitmap ** ppIBitmap) 
Parameters: 

pMe [in] Pointer to the OEM Display Interface. 


ppIBitmap [out] Pointer to the interface of device bitmap. 


Return Value: 
SUCCESS if the function performed correctly. 
ENOMEMORY if there was not enough memory for the operation. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP GetPaletteEntry() 


Description: 


This function gets an entry in the device's palette table. If the device does not support 
a dynamic palette, the function returns EUNSUPPORTED. 


Prototype: 


int IOEMDisp GetPaletteEntry 
( 
IOEMDisp *pMe, 
RGBVAL *pRGB, 
unsigned int index 


) 











Parameters: 


pMe [in] Pointer to the OEM Display Interface. 
pRGB [out] Value of the palette entry. 
index [in] Index of palette entry to retrieve. 


Return Value: 
SUCCESS if the function performed correctly. 
EUNSUPPORTED if the device does not have a dynamic palette. 


Comments: 
None 


See Also: 
IOEMDISP SetPaletteEntry() 
IOEMDISP MapPalette() 
Return to the List of functions 
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IOEMDISP GetSymbol() 


Description: 


This function returns the AECHAR value corresponding to the specified symbol value. 
NOTE: This function is deprecated in BREW 2.1 and should return EUNSUPPORTED. 


Prototype: 


int OE 





DISP GetSymbol 


M 

( 

IOEMDisp *pMe, 
AECHAR *pChar, 
A 
A 
) 





EESymbol sym, 
EEFont font 

















Parameters: 


pMe [in] Pointer to the OEM Display Interface. 

pChar [out] Character value associated with the specified symbol. 
sym [in] Requested symbol. 

font [in] Requested font. 


Return Value: 
SUCCESS is returned if the function performed correctly. 
EFAILED if AECHAR pointer is NULL 
EUNSUPPORTED is returned if function is not implemented. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP GetSystemFont() 


Description: 
The function retrieves an interface to the font specified. A new instance of the font 
should be created for each call to this function. 


Prototype: 





DISP GetSystemFont 


( 

IOEMDisp * pMe, 
AFEFont font, 
1 
) 














Font ** pFont 


Parameters: 
pMe [in] Pointer to IOEMDisp interface. 
font [in] Requested font. 


pFont [out] Pointer to interface of font. 


Return Value: 
SUCCESS is returned if function performed correctly. 
EUNSUPPORTED if the specified font is not supported. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP MapPalette() 


Description: 
This function sets multiple entries in the device's palette table. It only sets a contiguous 
set of entries, starting from index O (zero). If the device does not support a dynamic 
palette, this function returns EUNSUPPORTED. 


Prototype: 
int IOEMDisp MapPalette 
( 
IOEMDisp *pMe, 
unsigned int cntRGB, 
RGBVAL *pRGB 
) 








Parameters: 
pMe Pointer to the OEM Display Interface. 
cntRGB Number of entries to set. 
pRGB Array of colors that are to be used in the palette. 


Return Value: 
SUCCESS if the function performed correctly. 
EUNSUPPORTED if the device does not have a dynamic palette. 


Comments: 
None 


See Also: 
IOEMDISP SetPaletteEntry() 
IOEMDISP GetPaletteEntry() 
Return to the List of functions 
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OEMDisp New() 


Description: 
This function creates a new instance of the IOEMDisp interface. 

















Prototype: 

int OEMDisp New(IShell * ps, AEECLSID cls, void ** ppif) 
Parameters: 

ps [in] Pointer to the IShell interface. 

cls [in] Class ID of the new IOEMDisp interface. 


ppif [out] Pointer to the new OEM Display Interface. 


Return Value: 
SUCCESS is returned if the function performed correctly. 
EBADPARM if the parameters are invalid 
ENOMEMORY if there is not enough memory 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP SetAnnunciators() 


Description: 
This function turns annunciators on or off. Two bitmasks are passed as parameters: 
wMask and wVal.The bits set in wMask select the corresponding annunciators. For 
each of the selected annunciators, the bits in wVal indicate whether the corresponding 
annunciator needs to be turned on or off. 


Prototype: 
int IOEMDISP SetAnnunciators 
( 
IOEMDisp *pMe, 
unsigned int wVal, 
unsigned int wMask 


) 








Parameters: 
pMe Pointer to the OEM Display Interface. 
wVal Annunciator bitmask values. 


wMask Annunciator bitmask masks. 


Return Value: 
SUCCESS is returned if the function performed correctly. 
EUNSUPPORTED if the operation is not supported. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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IOEMDISP SetPaletteEntry() 


Description: 
This function sets an entry in the device's palette table. If the device does not support 
a dynamic palette, this function returns EUNSUPPORTED. 


Prototype: 


int IOEMDisp SetPaletteEntry 
( 
IOEMDisp * pMe, 
unsigned int index, 
RGBVAL rgb 
) 











Parameters: 
pMe Pointer to the OEM Display Interface. 
index Index of palette entry to change. 
rgb Color to put in the palette. 


Return Value: 
SUCCESS if the function performed correctly. 
EUNSUPPORTED if the device does not have a dynamic palette. 


Comments: 
None 


See Also: 
IOEMDISP GetPaletteEntry() 
IOEMDISP MapPalette() 
Return to the List of functions 
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IOEMDISP Update() 


Description: 
This function updates the graphic memory (display) using the contents of the shadow 
buffer. The function can do either of the following: 
* Deferred refresh where the update waits for any ongoing draw operations to 
complete. 
* Forced refresh where the update happens immediately. 








Prototype: 

int IOEMDISP Update (TIOEMDisp *pMe, boolean bDefer) 
Parameters: 

pMe Pointer to the OEM Display Interface. 


bDefer Flag that determines whether to do a deferred update or a forced update. 


Return Value: 
SUCCESS is returned if the function performed correctly. 
Other implementation-specific error codes. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM File System Interface 


This section describes the File System interface functions that the AEE uses. The interface 
provides a basic foundation for simple file system operations. 


List of functions 


Functions in this interface include: 


OEMFS Close() 
OEMFS EnumNext() 
OEMFS EnumsStart() 
OEMFS EnumStop() 
OEMFS GetDirlnfo() 
OEMFS GetFileAttributes() 
OEMFS GetLastError() 
OEMFS GetOpenFileAttributes() 
OEMFS Mkdir() 
OEMFS Opent() 
OEMFS Read() 
OEMFS Remove() 
OEMFS Rename() 
OEMFS Rmdir() 
OEMFS Seek() 
OEMFS SpaceAvail() 
OEMFS SpaceUsed() 
OEMFS Tell() 

OEMFS Test() 

OEMFS Truncate() 
OEMFS Write() 


The remainder of this section provides details for each function. 
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OEMFS Close() 


Description: 


This function closes the file identified by pFileHandle. The function takes the file 
handle returned by OEMFS Opent() and frees all resources associated with it. 
Subsequent operations on the file handle fail. 


Prototype: 


int OEMFS Close(void * pFileHandle) 





Parameters: 
pFileHandle File handle retumed from OEMFS Opent(). 


Return Value: 
SUCCESS if the operation was successful 
Valid BREW-defined error code, otherwise. 
EMEMPTR: "pFileHandle" does not point to a valid handle 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


Side Effects: 


Any OEM-specific memory structures associated with the file are closed. 


See Also: 
OEMFS Opent() 
Return to the List of functions 
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OEMFS EnumNext() 


Description: 
This function uses the file or directory enumeration control object referenced by 
plterator to return file information for the next file or directory specified in 
OEMFS EnumsStart(). The function returns not only the name, but all of the other 
parameters of AEEFilelnfo, including flags, creation date, and file size. 
Upon success, the OEMFSEnum object will contain the values associated with the 
enumerated file or directory. 


Prototype: 


int OEMFS EnumNext 


























( 
OEMF SEnum *pcxt 
) 


Parameters: 


pcxt Input/Output structure for the enumeration operation. 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


SUCCESS error code if no more items are to be enumerated. The function fills pInfo 
with zeros. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
OEMFS EnumStart() 
OEMFS EnumsStop() 
OEMFS GetLastError() 
Return to the List of functions 
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OEMFS EnumsStart() 


Description: 


This function initializes a file or directory enumeration control object for use by 
subsequent calls to OEMFS EnumNext(). Enumeration can be of either files or 
directories in the parent directory szDir. To enumerate files, the isDir parameter is 
zero. To enumerate directories, the value is non-zero. 


Prototype: 


OEMF SEnum * OEMFS EnumStart 
( 
const char*szDir, 
charisDir 


) 























Parameters: 


szDir Directory to be enumerated. 
isDir Flag to indicate enumeration of files or directories. 


Return Value: 


Returns a pointer to the structure that will be populated with the results of all future 
OEMFS EnumNext() operations. 


Comments: 


BREW will reference members of the OEMFSEnum only during the time that it is valid 
(between OEMFS EnumsStart() and OEMFS EnumsStop()) 


This function should set an internal error value that can be retrieved with 
OEMFS GetLastError(). 


Common error codes: 
EFILENOEXISTS: If an element of the directory path does not exist 


EBADFILENAME: If "szDir" is NULL, empty or longer than 
AEE MAX FILE NAME 


Side Effects: 


This function allocates memory to hold the structure. 


See Also: 
OEMFS EnumNext() 
OEMFS EnumsStop() 
Return to the List of functions 
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OEMFS EnumsStop() 


Description: 
This function frees any resources associated with an enumeration. 


Prototype: 


int OEMFS EnumStop 


























( 
OEMF SEnum *pcxt 
) 


Parameters: 


pext Enumeration control object returned from OEMFS EnumsStart int 
OEMFS EnumsStop(void * plterator) 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 
EMEMPTR: if "plterator" is not valid 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
OEMFS EnumsStart() 
OEMFS EnumNext() 
Return to the List of functions 
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OEMFS GetDirlnfo() 


Description: 
Get the following information about the given directory: 
- Number of files in this directory (including sub-directories) 
- Total space occupied by this directory (including sub-directories) 


Prototype: 


int OEMFS GetDirInfo 
( 
IFileMgr *pfm, 
const char* pszDir, 
uint1l6 *pwCount, 
uint32 *pdwSize 
); 





Parameters: 
pfm Pointer to IFileMgr interface 
pszDir Directory whose info is needed. The AEE function AEE  BuildPath() 
must be used to build the complete path specified by pszDir. 
pwCount If non Null on input, *pwCount must contain the total number of files in 
this directory tree on retum 
pdwSize If non NULL on onput, *pdwSize must contain the total space occuped 


by this directory tree on retum 


Return Value 
AEE SUCCESS, if successful 
EFAILED, if failed 


Comments: 
None 


See Also: 
None 


Return to the List of functions 
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OEMFS GetFileAttributes() 


Description: 
This function returns the following file attributes of the file specified by szFilename: 
* Flags (Hidden, System, Directory) 
* Creation date in seconds from the beginning of the GPS epoch 
* File size 
* Filename 


The attributes matched are exactly the same as those currently returned to the 
programmer by the upper level API. 


Prototype: 
int OEMFS GetFileAttributes 
( 
const char * szFilename, 
AEEFileInfo * pInfo 
) 














Parameters: 


szFilename Name of the open file 
pInfo Pointer to a structure used to return the file attributes 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS GetLastError() 


Description: 


This function gets the last error produced by the OEMFS subsystem. If the last 
operation was successful, this function returns SUCCESS. 


Prototype: 


int OEMFS GetLastError (void) 








Parameters: 
None 


Return Value: 
SUCCESS if successful. 
Valid BREW-defined error code if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMFS GetOpenFileAttributes() 


Description: 
This function returns the following file attributes of the currently open file specified by 
pFileHandle: 
* Flags (Hidden, System, Directory) 
* Creation date in seconds from the beginning of the GPS epoch 
* File size 
* Filename 


Prototype: 


int OEMFS GetOpenFileAttributes 
( 
void* pFileHandle, 
const char* szFilename, 
ABEFileInfo *pInfo 
) 

















Parameters: 


pFileHandle File handle returned by OEMFS Opent(). 
szFilename Name of the open file. 
pInfo Pointer to structure used to return data. 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Mkdir() 


Description: 


This function creates a new user file directory named dirname. This directory is 
created as long as the new directory's parent directories exist. 


Prototype: 


int OEMFS Mkdir (const char * dirname) 





Parameters: 


dimame Name of new directory. 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


This function sets an internal error value that can be retrieved with 
OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Open() 


Description: 


This function opens the file specified by szFilename for the type of access specified 
by nMode. The function allocates and initializes a data structure that it returns. The 
current file position is set to be the beginning of the file. 


Prototype: 


void* OEMFS Open (const char * szFilename, AFEEOpenFileMode nMode) 

















Parameters: 


szFilename Name of file to open. 
nMode File open mode, which ttakes the following values: 
-OFM READ: File is opened for read only and will not create a file. 


- OFM READWRITE: File is opened in readwrite mode and will not 
create a file. 


-OFM APPEND: Same as OFM READWRITE but sets the file 
pointer to the end of the file. . 


- OFM CREATE: Creates a new file in read/write mode. An error is 
generated, and no file opened, if the file already exists. 


Return Value: 


Pointer identifying the open file. The AEE does not attempt to de-reference the pointer, 
but instead passes it as a parameter to all functions that act upon the open file (such 
as read, write, and truncate). 


NULL if there is an error. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
OEMFS Close() 
Return to the List of functions 
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OEMFS Read() 


Description: 
This function reads nBytes bytes from the file identified by pFileHandle into buffer 
starting at the current file pointer position associated with pFileHandle. The number of 
bytes actually read is returned. If an error occurs with the operation, O (zero) is 





returned. 
Prototype: 

uint32 OEMFS Read(void * pFileHandle, void * buffer, uint32 nBytes) 
Parameters: 

pFileHandle Handle of file to read, returned by OEMFS Open(). 

buffer Buffer with bytes to read. 

nBytes Number of bytes to read. 


Return Value: 
Number of bytes read from the buffer. 
O (zero) if there is an error, including an End-Of-File (EOF) error. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


Side Effects: 


The current file pointer position is incremented so that it points immediately after the 
last byte returned. 


See Also: 
OEMFS Write() 
Return to the List of functions 
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OEMFS Remove() 


Description: 
This function removes the file identified by Filename. 


Prototype: 


int OEMFS Remove (const char * Filename) 





Parameters: 


Filename Name of file to remove 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Rename() 


Description: 


This function renames the file identified by old filename, the old filename, to 
new filename, the new filename. 





Prototype: 

int OEMFS Rename (const char * old filename, const char * new filename) 
Parameters: 

old filename Current name of the file. 


new filename New name of the file. 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Rmdir() 


Description: 
This function removes the user file directory specified by dirname. 


Prototype: 


int OEMFS Rmdir (const char * dirname) 





Parameters: 


dirname Directory to remove. 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Seek() 


Description: 
This function sets the current file pointer position of the file associated with 
pFileHandle from a starting point sType, offset by a number of bytes (positive or 
negative) specified by nOffset. The sType parameter can be one of three values: 
* SEEK START (offset is based on the beginning of the file) 
* SEEK END (offset is based on the end of the file) 
* SEEK CURRENT (offset from the current position) 


lfthe new seek pointer is beyond the end of the file, the file is enlarged to accomodate 
the seek. 


Prototype: 
int OEMFS Seek 
( 
void * pFileHandle, 
AEEFileSeekType sType, 
int32 nOffset 
) 

















Parameters: 
pFileHandle File handle returned by OEMFS Opent(). 
sType Type of seek starting point. 
nOffset Offset from starting point. 


Return Value: 
SUCCESS if the operation was successful 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


Side Effects: 


Sets the current file position associated with pFileHandle to the specified position. 


See Also: 
None 
Return to the List of functions 
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OEMFS SpaceAvail() 


Description: 
This function returns the amount of available file system space (in bytes). 


Prototype: 


uint32 OEMFS SpaceAvail (void) 





Parameters: 
None 


Return Value: 
Number of bytes of file system space currently available. 


Comments: 


The file service handling task must have been started already. This function does not 
set or return an error. 


See Also: 
None 
Return to the List of functions 
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OEMFS SpaceUsed() 


Description: 


This function returns the amount offile system space (in bytes) in use. The function call 
is synchronous and does not involve the file service handling task command queues. 


Prototype: 


uint32 OEMFS SpaceUsed (void) 





Parameters: 
None 


Return Value: 
Number of bytes of file system space currently in use. 


Comments: 


The file service handling task must have been started already. This function does not 
set or return an error. 


See Also: 
None 
Return to the List of functions 
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OEMFS Tell() 


Description: 


This function returns the current file pointer position of the file associated with 
pFileHandile. 


Prototype: 


int OEMFS Tell(void * pFileHandle) 





Parameters: 
pFileHandle File handle retumed from OEMFS Opent(). 


Return Value: 
Offset from beginning of the file if successful. 
-1 if an error occurs with the operation. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Test() 


Description: 


This function tests for the existence of a file or a directory. It first checks if the directory 
exists, and then checks the specified name. 


Prototype: 


int OEMFS Test (const char * filename) 





Parameters: 


filename File or directory to check for existence. 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Truncate() 


Description: 


This function truncates the file identified by pFileHandle to the position specified by 
nPos. The file must not be open for read only operations. The offset must be less than 
the total length of the file. 


Prototype: 


int OEMFS Truncate (void * pFileHandle, uint32 nPos) 





Parameters: 


pFileHandle File handle. 
nPos File truncate position (new file size). 


Return Value: 
SUCCESS if the operation was successful. 
Valid BREW-defined error code, otherwise. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


See Also: 
None 
Return to the List of functions 
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OEMFS Write() 


Description: 


This function writes nBytes bytes from buffer into the file identified by pFileHandle 
starting at the current file pointer position associated with pFileHandle. The number of 
bytes actually written is retumed following operation completion. 


Prototype: 


uint32 OEMFES Write 
( 
void * pFileHandle, 
const void * buffer, 
uint32 nBytes 
) 





Parameters: 
pFileHandle Handle of file to write to, returned by OEMFS Opent(). 
buffer Buffer with bytes to write. 
nBytes Number of bytes to write. 


Return Value: 
Number of bytes written to the buffer. 
O (zero) if there is an error. 


Comments: 


The file service handling task must have been started already. This function sets an 
internal error value that can be retrieved with OEMFS GetLastError(). 


Side Effects: 


The current file pointer position is incremented so that it points immediately after the 
last byte returned. 


See Also: 
OEMFS Read() 
Return to the List of functions 
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This section describes the basic heap memory routines that the AEE files use to provide 
memory management functionality. 


List of functions 


Functions in this interface include: 


OEM CheckMemaAvail() 
OEM Free() 

OEM GetRAMFree() 
OEM InitHeap() 

OEM Malloc() 

OEM Realloc() 


The remainder of this section provides details for each function. 
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OEM CheckMemAvail() 


Description: 


This function checks to see if a memory block of the given size can be allocated. The 
function does not allocate memory, it simply returns TRUE or FALSE to indicate 
whether it is possible to allocate a block of the given size. 


Prototype: 


boolean OEM CheckMemAvail (uint32 dwSize) 





Parameters: 


dwSize Size of the block whose allocation is to be verified. 


Return Value: 
TRUE if a memory block of the given size can be allocated. 
FALSE if a block of the given size cannot be allocated. 


Comments: 
None 


Side Effects: 


This function may walk through the heap and collapse adjacent free blocks, if any are 
available. 


See Also: 
None 
Return to the List of functions 
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OEM Free() 


Description: 
This function frees an allocated memory buffer. 


Prototype: 


void OEM Free(void * pBuff) 





Parameter(s): 
pBuff Pointer to buffer that is to be freed. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM GetRAMFree() 


Description: 


This function returns the number of free bytes in the heap. It conditionally fills the 
values of the total heap size and the largest block that can be allocated. 





Prototype: 
uint32 OEM GetRAMFree (uint32 * pdwTotal, uint32 * pdwMax) 
Parameter(s): 
pdwTotal Pointer to the value to set with the total space in the file system. 
pdwMax Pointer to the value to set with the maximum size block that can be 


allocated. 


Return Value: 
Number of free bytes in the heap. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM InitHeap() 


Description: 
This function initializes the heap sub-allocator. 





Prototype: 

void OEM InitHeap (void * pMem, uint32 dwSize) 
Parameter(s): 

pMem Memory buffer. 

dwSize Size in bytes. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Malloc() 


Description: 
This function allocates a buffer from the heap. 


Prototype: 


void * OEM Malloc (uint32 dwNewSize) 





Parameter(s): 


dwNewSize Size, in bytes, of the buffer to be allocated from the heap. 


Return Value: 
Pointer to the allocated buffer if successful. 
NULL if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Realloc() 


Description: 
This function allocates or reallocates a buffer from the heap. 





Prototype: 

void * OEM Realloc(void * pBuff, uint32 dwNewSize) 
Parameter(s): 

pBuff Buffer or NULL. 


dwNewSize New size of the buffer. 


Return Value: 
Pointer to the rellocated buffer if successful. 
NULL if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Description: 


BREW provides a standardized and extensible data logging interface, which allows a BREW 
application developer to log data using a number of different transport mechanisms. 


Below are the primary logging transport implementations. A BREW application developer 
selects one by creating an ILogger instance with one of the following class IDs: 





Class ID Description 
AEECLSID LOGGER FILE Sends log items to a file. 
AEECLSID LOGGER WIN Sends log items to the Emulator output window. 


Each implementation is responsible for handling and writing to a specific transport but the data 
being sent is transport independent. 


The header file AEELoggerTypes.h provides definitions for the logging data types common to 
both BREW's ILogger interface and the PC side log parser in a client/server type of 


architecture. 


The file implementation outputs data to the output file in the following BREW packet format: 





BREW header Packet data 





The Windows implementation of the ILogger interface writes all outgoing logs to the BREW 
output window using the following format: 


bkt:xx typ:xx clD:xx ilD:xx FILENAME LINENUMBER MESSAGE ARGS 
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in which 

bkt Log bucket 

typ Log type 

clD ClassiD of the currently running BREW application 
ID User-defined instance ID 

FILENAME Optional file name where log was sent 


LINENUMBER Optional line number where log was sent 
MESSAGE User defined text message 


ARGS Optional arguments using OEMLogger PutMsg() 


When compiling a release version of a BREW application, the constant AEE LOG DISABLE 
may be defined, which, using the preprocessor, removes all OEMLogger interface logging 
functions, except the instance creation and getting and setting parameters processes. This 
constant must be defined before a new BREW application includes AEELogger.h. 


The contents of log data is determined by the type element of the BREW Log header. Three 
standard log types are predefined by BREW, but the BREW application developer can also 
define as many custom log types as required. The three standard BREW-defined log types are 
as follows: 


Type Description Data contains 





AEE LOG TYPE TEXT ASClltextmessage Ifyou use this log type, the data contains 
nSize bytes of ASCII text. 


AEE LOG TYPE BIN MSG  AEELogTypeBinMsg Ifyou use this log type, the data contains one 
AEE LogTypeBinMsg structure. 


AEE LOG TYPE BIN BLK Block of arbitrary If you use this log type, the data contains 
binary data nSize bytes of arbitrary binary data. 


Do 
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Log items are sent and filtered in one of 255 distinct, general purpose buckets. These log 
buckets are filtered by the developer at run time using ILOGGER SetParam() and 
ILOGGER GetParam() or on the PC side, using a post processor. 


The structure AEELogTypeBinMsg contains the following elements: 





Element Description 
Header b7,b6 — bits reserved 
b5,b4 — number of args 
b3 bit — file name present 
b2,b1,b0 — message level 
Line Line number in application code where this log 


args[ MAX LOG TYPE BIN MSG ARGS] 


pszMsg[ MAX LOG TYPE BIN MSG TEXT SIZE ] 





List of Header files to be included 


The following header file is required: 


OEMLogger.h 
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item was sent 
Contains zero or more 32 bit integer values 


pszMsg contains two consecutive NULL 
terminated strings: the first is the file name 
where the log message was sent and the 
second is an ASCII text message 
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List of functions 


Functions in this interface include: 


OEMLogger Printf() 
OEMLogger Putltem() 
OEMLogger PutMsg() 
OEMLoggerDMSS GetParam() 
OEMLoggerDMSS PutRecord() 
OEMLoggerDMSS SetParam() 
OEMLoggerFile GetParam() 
OEMLoggerFile PutRecord() 
OEMLoggerFile SetParam() 
OEMLoggerWin GetParam() 
OEMLoggerWin PutRecord() 
OEMLoggerWin SetParam() 


The remainder of this section provides details for each function. 
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OEMLogger Printf() 


Description: 


This function is called to send a prioritized formatted ASCII text message. Since this 
routine is a MACRO that allows variable arguments it must be called as follows: 





OEMLogger Printf( pMe->m pILogger, 
( pMe->m pILogger, 
USER BUCKETIA, 
— FILE, 
(uint16) LINE 
"msg" r 
args ) 














); 
Notice that the second argument is actually multiple arguments in parentheses, and 
args can be multiple comma separated values 


Prototype: 


int OEMLogger Print f 
( 
ILogger *pMe, 
ABELogBucket Type bucket, 
const char *pszFileName, 
uint16 nLineNum, 
const char *pszFormat, 
Ji 














Parameters: 
pMe Pointer to the OEMLogger Interface object 
bucket Bucket to place item 
pszFileName Name of file calling this function 
nLineNum Line number in file where it was called 


pszFormat ASCII text string similar to a printf format string 
Format string arguments 


Return Value: 

SUCCESS Log send successfully 

EBADPARM Invalid pointer to pszFormat 

EUNSUPPORTED Log item filtered 

ENOMEMORY Unable to allocated required memory 

EFAILED Log not sent 

-- The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 
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Comments: 
None 


See Also: 
AEELogBucketType 
Return to the List of functions 
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OEMLogger Putltem() 


Description: 
This function is called to send a prioritized user defined binary message. 


To define a user log item type: 


1. Select a user item number and define a meaningful name to it, For Example: 





fdefine MY APPS LOG ITEM TYPE AEE LOG TYPE USER 1 


























2. Define a structure that corresponds to you're new type, Example: 


typedef struct( 
uint8 fool; 
uint32 foo2; 
uint8 fooString[ STRING SIZE 1; 
) myAppsItem; 





3. Enable the PC software that will be reading the logging output to recognize the log 
item type AEE LOG TYPE USER 1 (which in this case is 
MY APPS LOT ITEM TYPE) 


4. Call OEMLogger Putltem() with MY APPS LOT ITEM TYPE, a pointer to an 
instance of myAppsltem, and the size of myAppsltem. 


Prototype: 


int OEMLogger PutItem( ILogger *pMe, 
ABEELogBucket Type bucket, 
ALELogitemType type, 
uint16 nsize, 
uint8 *pItem ) 


























Parameters: 
pMe Pointer to the OEMLogger Interface object 
bucket Bucket to place item 
type User defined item type 
nSize Size of type in bytes 
pltem Pointer to instance of type 


Return Value: 
SUCCESS Log send successfully 
EBADPARM Invalid pointer to pltem or size equal to zero 
EUNSUPPORTED Log item filtered 
ENOMEMORY Unable to allocated required memory 
EFAILED Log not sent 
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The following log codes only apply to file logging 


EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 


AEELogBucketType 
AEELogltemType 


Return to the List of functions 
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OEMLogger PutMsg() 


Description: 


This function is called to send a prioritized predefined binary message and allows fast 
logging due to the limited formatting required and the fixed size of the outgoing log 
message. The outgoing binary message's data of type structure AEELogBinMsgType, 
which is defined in AEELoggerTypes.h. 


Prototype: 


int OEMLogger PutMsg( ILogger *pMe, 
AFEELogBucket Type bucket, 
const char *pszFileName, 
uint16 nLineNum, 
const char *pszMsg, 
uint8 nNumArgs, 
uint32 args[ MAX LOG TYPE BIN MSG ARGS 1] ) 























Parameters: 
pMe Pointer to the OEMLogger Interface object 
bucket Bucket to place item 
pszFileName ASCII NULL terminated name of file calling this function 
nLineNum Line number in file where it was called 
pszMsg ASCII NULL terminated text message 
nNumArgs length of the args array 
args array containing uint32 arguments 


Return Value: 

SUCCESS Log send successfully 

EBADPARM Invalid pointer to pszMsg or nNumArgs too large 

EUNSUPPORTED Log item filtered 

ENOMEMORY Unable to allocated required memory 

EFAILED Log not sent 

The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 
AEELogBucketType 
AEELogBinMsgType 
Return to the List of functions 
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OEMLoggerDMSS GetParam() 


Description: 
This function is called to get the configuration of the OEM logging interface. 


Prototype: 

int OEMLoggerDMSS GetParam 
( 
ILogger *po, 
ALELogParamType pType, 
void* pParam 


) 




















Parameters: 
pMe Pointer to the ILogger object 
pType Parameter to modify 
pParam Pointer to settings parameter to fill 


Return Value: 
EMEMPTR: Invalid pParam pointer if pParam is required for this LogParamType 
SUCCESS: LogParamType handled successfully 
EUNSUPPORTED: The log parameter is not supported 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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OEMLoggerDMSS PutRecord() 


Description: 


This function is called by ILOGGER Printf(), ILOGGER Putltem(), or 
ILOGGER PutMsg() to output a log record to the DMSS Diag task. 


Prototype: 
int IOGGER PutRecord 
( 


ILogger *po, 
AEELogBucket Type bucket, 
A 

) 














mm 
E 


ELogRecord *pRcd 





Parameters: 
pMe: Pointer to the ILOGGER object 
bucket: Bucket to place item 
pltem: Pointer to data with BREW header at beginning to write to log 


Return Value: 
SUCCESS Item data written successfully 
EBADPARM Invalid pointer to pltem 
EFAILED General failure 
-- The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 
AEELogBucketType 
Return to the List of functions 
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OEMLoggerDMSS SetParam() 


Description: 


This function is called to set performance and behavior of the logging interface. 
Supported parameters depends on the current implementation's support, 


Prototype: 


int OEMLoggerDMSS SetParam 
( 
ILogger *po, 
ALELogParamType pType, 
uint32 param, 

void* pParam ) 




















Parameters: 
pMe Pointer to the ILogger object 
pType Parameter to modify 
param New settings parameter 
pParam Pointer to new settings parameter 


Return Value: 
EMEMPTR: Invalid pParam pointer if pParam is required for this LogParamType 
SUCCESS: LogParamType handled successfully 
EFAILED: General failure 
EUNSUPPORTED: The log parameter is not supported 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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OEMLoggerFile GetParam() 


Description: 
This function is called to get the configuration fo the ILogger interface. Supported 
parameters depends on the current implementation's support, 


Prototype: 

int OEMLoggerFile GetParam 
( 
ILogger *po, 
ALELogParamType pType, 
void* pParam 


) 




















Parameters: 
pMe Pointer to the ILogger object 
pType Parameter to modify 
pParam Pointer to be filled with settings parameter 


Return Value: 
EMEMPTR: Invalid pParam pointer if pParam is required for this LogParamType 


SUCCESS: LogParamType handled successfully 
EUNSUPPORTED: The log parameter is not supported 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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OEMLoggerFile PutRecord() 


Description: 


This function is called by ILOGGER Printf(), ILOGGER Putltem(), or 
ILOGGER PutMsg() to output a log record to the output log file. 


Prototype: 


int ILOGGER PutRecord 

( 

ILogger *po, 
ABEELogBucket Type bucket, 
AEELogRecord *pRcd 
) 























Parameters: 
pMe Pointer to the ILOGGER object 
bucket Bucket to place item 
pRcd Pointer to data with BREW header at beginning to write to log 


Return Value: 
SUCCESS Item data written successfully 
EBADPARM Invalid pointer to pltem 
EFAILED General failure 
The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 
AEELogBucketType 
Return to the List of functions 
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OEMLoggerFile SetParam() 


Description: 


This function is called to set performance and behavior of the logging 
interface.Supported parameters depends on the current implementation's support, 


Prototype: 


int OEMLoggerFile SetParam 
( 
ILogger *po, 
ALELogParamType pType, 
uint32 param, 
void* pParam 


) 




















Parameters: 
pMe Pointer to the ILogger object 
pType Parameter to modify 
param New settings parameter 
pParam Pointer to new settings parameter 


Return Value: 
EMEMPTR: Invalid pParam pointer if pParam is required for this LogParamType 
SUCCESS: LogParamType handled successfully 
EUNSUPPORTED: The log parameter is not supported 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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OEMLoggerWin GetParam() 


Description: 
This function is called to get the configuration fo the ILogger interface.Supported 
parameters depends on the current implementation's support, 


Prototype: 

int OEMLoggerWin GetParam 
( 
ILogger *po, 
ALELogParamType pType, 
void* pParam 


) 




















Parameters: 
pMe: Pointer to the ILogger object 
pType: Parameter to modify 
pParam: Pointer to be filled with settings parameter 


Return Value: 
EMEMPTR: Invalid pParam pointer if pParam is required for this LogParamType 


SUCCESS: LogParamType handled successfully 
EUNSUPPORTED: The log parameter is not supported 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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OEMLoggerWin PutRecord() 


Description: 


This function is called by ILOGGER Printf(), IOGGER Putltem(), or 
ILOGGER PutMsg() to output a log record to the BREW Emulator output window. 


This function only supports text output and therefore only supports log types 
AEE LOG TYPE TEXT and AEE LOG TYPE BIN MSG. 


























Prototype: 
int OEMLoggerWin PutRecord 
( 
ILogger *po, 
AFELogBucket Type bucket, 
AEELogRecord *pRcd 
) 
Parameters: 
pMe Pointer to the ILOGGER object 
bucket Bucket to place item 
pltem Pointer to data with BREW header at beginning to write to log 


Return Value: 
SUCCESS Item data written successfully 
EBADPARM Invalid pointer to pltem 
EFAILED General failure 
The following log codes only apply to file logging 
EFSFULL Not enough space in log file for this packet 
EFILENOEXISTS Output log file is closed 


Comments: 
None 


See Also: 
AEELogBucketType 
Return to the List of functions 
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OEMLoggerWin SetParam() 


Description: 


This function is called to set performance and behavior of the logging interface. 
Supported parameters depends on the current implementation's support, 


Prototype: 


int OEMLoggerWin SetParam 
( 
ILogger *po, 
ALELogParamType pType, 
uint32 param, 
void* pParam 


) 




















Parameters: 
pMe Pointer to the ILogger object 
pType Parameter to modify 
param New settings parameter 
pParam Pointer to new settings parameter 


Return Value: 
EMEMPTR: Invalid pParam pointer if pParam is required for this LogParamType 
SUCCESS: LogParamType handled successfully 
EUNSUPPORTED: The log parameter is not supported 


Comments: 
None 


See Also: 
AEELogParamType 
Return to the List of functions 
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OEM MDS Interface 


This section describes the functions in the OEM MDS interface. 
List of functions 
Functions in this interface include: 


OEMMDS5 Final() 
OEMMDS Init() 
OEMMDS5 Update() 


The remainder of this section provides details for each function. 
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OEMMDS Final() 


Description: 


This function ends an MD5 message-digest operation, writing the message digest and 
changing the context to O (zero). 








Prototype: 

void OEMMD5 Final (uint8 digest [16], OEMMD5S CTX * context) 
Parameters: 

digest Message digest. 

context Pointer to the MD5 context. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMMDS Init() 


Description: 
This function begins an MD5 operation, writing a new context. 


Prototype: 


void OEMMD5 Init (OEMMDS CTX * context) 








Parameters: 


context Pointer to a context that will be initialized. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMMDS5S Update() 


Description: 


This function continues an MD5 message-digest operation, processing another 
message block and updating the context. 


Prototype: 


void OEMMD5 Update 
( 








OEMMD5S CTX * context, 
uint8 * input, 

uint32 inputLen 

) 


Parameters: 
context MDS context. 
input Input block. 


inputLen Length of the input block. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Net Interface 


The OEM Net interface provides the underlying networking services required for sockets to 
operate. Primarily this consists of functions for managing PPP, with a few additional utility 
functions. If an operation is unable to complete immediately, it should return an error code of 
AEE NET EWOULDBLOCK. When the operation completes, call AEE NetEventOccurred to 
notify BREW. 


The following functions are optional and may return EUNSUPPORTED: 


OEMNet GetPPPAuth() 
OEMNet GetRLP3Cfg() 


OEMNet GetUrgent() 
OEMNet SetPPPAuth() 
OEMNet SetRLP3Cfg() 


List of functions 


Functions in this interface include: 


OEMNet CloseNetlib() 
OEMNet GetPPPAuth() 
OEMNet GetRLP3Cfg() 
OEMNet GetUrgent() 
OEMNet MylIPAddr() 
OEMNet NamesServers() 
OEMNet OpenNetlib() 
OEMNet PPPClose() 
OEMNet PPPOpen() 
OEMNet PPPSleep() 
OEMNet PPPState() 
OEMNet SetPPPAuth() 
OEMNet SetRLP3Cfg() 


The remainder of this section provides details for each function. 
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OEM Net Interface 


OEMNet CloseNetlib() 


Description: 


This function closes the network library for the application. All sockets must have been 
closed for the application before closing the library. If this is the last remaining 
application, the network subsytem (PPP/traffic cnannel) must also be brought down 
before closing the library. The function is called from the context of the socket client's 


task. 


Prototype: 


intl6 O! 





Parameters: 
None 


EMNet CloseNetlib(void) 


Return Value: 


AEE NE 
AEE des 


Comments: 
None 


See Also: 


T SUCCESS, if successful 
ignated error codes indicating reason for failure, if otherwise 


OEMNet OpenNetlib() 
Return to the List of functions 
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OEMNet GetPPPAUth() 


Description: 


This function allows the caller to retrieve the configured PPP authentication settings, if 
this is relevant to the network implementation. 





Prototype: 
int 16 OEMNet GetPPPAuth (char *pszAuth, int *pnLen) 
Parameters: 
pszAuth [out] The buffer into which the credentials are to be copied, in the 


form of 2 concatenated, null terminated strings, for example: 
“userid(Dvzw.comid00passwordi000” 

pnLen [in/out] The size of pszAuth. If pszAuth is NULL, pnLen is ignored 
on input, and set to the number of bytes required to hold 
authentication information on output. 


Return Value: 
SUCCESS, if the credentials were retrieved 
EUNSUPPORTED, if PPP authentication cannot be retrieved 
EBADPARM, if pszAuth is not-NULL and pnLen is less than or equal to O (zero). 


Comments: 
None 


See Also: 
OEMNet SetPPPAuth() 
Return to the List of functions 
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OEMNet GetRLP3Cfg() 


Description: 


This function allows the caller to discover the configured RLP settings, if the OEM's 
network layer is implemented using RLP. 

















Prototype: 
int 16 OEMNet GetRLP3CfÍg (int1l6 nOptName, AEERLP3CÊÍg *prlp3) 
Parameters: 
nOptName One of 3 values 
INET OPT DEF RLP3 retrieve default RLP3 settings 
INET OPT CUR RLP3 retrieve current RLP3 settings 
INET OPT NEG RLP3 retrieve negotiated RLP3 settings 
prip3 [out] filled with relevant settings 


Return Value: 
SUCCESS, if the settings were retrieved 
EUNSUPPORTED, if RLP isn't employed or this API is otherwise unsupported 
AEE designated error codes indicating reason for failure, if otherwise 


Comments: 
None 


See Also: 
OEMNet SetRLP3Cfg() 
AEERLPSCTÍg 
Return to the List of functions 
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OEMNet GetUrgent() 


Description: 


Determines whether urgent sendto option is supported and the payload limit, if any. 
This function is synchronous, and therefore should not callback any notification 
function. 


Prototype: 


int 16 OEMNet GetUrgent 
( 











AEEUDPUrgent * pUrgent 








) 


Parameters: 
pUrgent pointer to AEEUDPUrgent struct 


Return Value: 
On success, returns AEE NET SUCCESS. 
On error, returns one of the AEE designated error codes indicating reason for failure. 


Comments: 
None 


See Also: 
AEEUDPUrgent 
Return to the List of functions 
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OEMNet MyIPAddr() 


Description: 
This function returns the IP address of the active session. 


Prototype: 


int 16 OEMNet MyIPAddr (INAddr * addr) 





Parameters: 


addr Pointer to the buffer used to hold the IP address, in network byte order. 


Return Value: 
AEE NET SUCCESS, if successful. 


Comments: 
Always returns success because failure conditions not currently defined. 


See Also: 
None 
Return to the List of functions 
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OEMNet NamesServers() 


Description: 


This function allows the caller to discover the configured name server addresses. The 
addresses may come from PPP setup or from phone configuration, or both. Ifit's both, 
the PPP addresses are listed first. 


Prototype: 


int 16 OEMNet NameServers (INAddr *ainaAddrs, int *pnNumAddrs) ; 





Parameters: 


ainaAddrs [in/out] a caller-allocated array of INAddrs, filled by INetMgr with the 
answer to the question: "which nameservers?" |f NULL, pnNumAddrs 
is filled with the number of addresses available . 

pnNumAddrs [in/out] caller sets this to array size of ainaAddrs, set by INetMgr to the 
number filled(if ainaAddrs is non-null)/available 


Return Value: 
SUCCESS, if the addresses are found, filled 


Comments: 


pnNumAddrs may be set to O, if there is no servers configured in NVRam and there is 
no PPP setup available the addresses returned in ainaAddrs must be in network byte- 
order 


See Also: 
INAddr 
Return to the List of functions 
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OEMNet OpenNetlib() 


Description: 


This function opens the network library and assigns the application ID. It sets the 
application-defined callback functions to be called when the library and socket calls 
make progress. The function is called from the context of the socket client's task. 


Prototype: 


int 16 OEMNet OpenNetlib (void) 





Parameters: 
None 


Return Value: 
AEE NET SUCCESS, if successful. 
AEE designated error code, if there is an error. 


Comments: 
None 


See Also: 
OEMNet CloseNetlib() 
Return to the List of functions 
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OEMNet PPPClose() 


Description: 


This function initiates termination to bring down any network connections started with 
OEMNet PPPOpent(). This function is asynchronous and must call 
AEE NetEventOccurred() upon completion of the close operation. 


Prototype: 


int 16 OEMNet PPPClose (void) 





Parameters: 
None 


Return Value: 
AEE NET SUCCESS, if successful. 
AEE designated error code, if there is an error. 


Comments: 
None 


See Also: 
OEMNet PPPOpen() 
OEMNet PPPState() 
Return to the List of functions 
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OEMNet PPPOpen() 


Description: 


This function starts the network subsystem (data service and PPP) and establishes a 
network connection to the internet. After the network is established, this function must 
call AEE NetEventOccurred() to indicate to the libraries that the connection is ready 
for use. 


Prototype: 


int 16 OEMNet PPPOpen (void) 





Parameters: 
None 


Return Value: 
AEE NET SUCCESS, if successful. 
AEE designated error code, if there is an error. 


Comments: 
None 


Side Effects: 


Initiates call origination and PPP negotiation. 


See Also: 
OEMNet PPPClose() 
OEMNet PPPState() 
Return to the List of functions 
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OEMNet PPPSleep() 


Description: 


This function releases data channel resources, but preserve PPP state basically: go to 
CDMA2000 dormant mode 


Prototype: 


int 16 OEMNet PPPSleep (void) 





Parameters: 
None 


Return Value: 
SUCCESS, if PPP is ASLEEP 
AEE NET EWOULDBLOCK, if dormancy is kicked off or in progress 


AEE NET EINVAL, if PPP is WAKING or CLOSED or the network hasn't been 
initialized with OpenNetLib() 


AEE NET EOPNOTSUPP, if dormancy can't be supported 


Comments: 


The OEM network state should transition to NET PPP SLEEPING or 
NET PPP ASLEEP synchronously, and AEE NetEventOccurred() must be called. 


See Also: 
None 
Return to the List of functions 


622 


Erevi OEM Net Interface 


OEMNet PPPState() 


Description: 
This function returns the state of the PPP connection. 


Prototype: 


NetState OEMNet PPPState (void) 





Parameters: 
None 


Return Value: 
State of PPP connection, if successful. 
NET INVALID STATE, if fails. 


Comments: 
None 


See Also: 
NetState 
OEMNet PPPOpen() 
OEMNet CloseNetlib() 
Return to the List of functions 
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OEMNet SetPPPAUth() 


Description: 


This function allows the caller to modify the configured PPP authentication settings, if 
this is relevant to the network implementation. 





Prototype: 
int 16 OEMNet SetPPPAuth (const char *cpszAuth) 
Parameters: 
cpszAuth The new credentials, in the form of 2 concatenated, null terminated 


strings, for example: “userid(Dvzw.comiO00passwordi000” 


Return Value: 
SUCCESS, if the credentials were set 
EUNSUPPORTED, if PPP authentication cannot be configured 


Comments: 
None 


See Also: 
OEMNet GetPPPAuth() 
Return to the List of functions 
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OEMNet SetRLP3Cfg() 


Description: 


This function allows the caller to modify the configured RLP settings, if the OEM's 
network layer is implemented using RLP. 


Prototype: 


int 16 OEMNet SetRLP3CÊÍg 














EERLP3CÍg *prlp3 





O 
( 
int 16 nOptName, 
A 
) 


Parameters: 
nOptName One of 2 values 
INET OPT DEF RLPS: set default RLP3 settings. 
INET OPT CUR RLP3: set current RLP3 settings. 
prip3 the new settings 


Return Value: 
SUCCESS, if the settings were configured 
EUNSUPPORTED, if RLP isn't employed or this API is otherwise unsupported 
AEE designated error code, if there is an error. 


Comments: 
None 


See Also: 
OEMNet GetRLP3Cfg() 
AEERLPSCÍg 
Return to the List of functions 
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OEM Registry Interface 


This section describes the OEM Registry-related function. 


List of functions 


Functions in this interface include: 


OEMRegistry DetectType() 


The remainder of this section provides details for each function. 
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OEMRegistry DetectType() 


Description: 


Given data in a buffer or the name of an object, this function detects the MIME type. 
This function is typically used to get the handler associated with the data type. For 
example, if the data represents standard MIDI format, then this function returns the 
MIME "audio/mid". Using the MIME type, you can query Shell registry to obtain the 
handler (Class ID) of type AEECLSID MEDIA. 


Prototype: 


int OEMRegistry DetectType 
( 
const void * cpBuf, 
uint32 * pdwSize, 
const char * cpszName, 
const char ** pcpszMIME 
Di; 








Parameters: 

cpBuf [in] Buffer containing the data whose type needs to be determined 

pdwSize [in/out] On input - Size of data in pBuf, unless pBuf is NULL, then ignored 
On output - number of additional data bytes needed to perform 
type detection 

cpszName [in] Name of the object whose type needs to be determined (may 
be null, if unknown). 

pcpszMIME [out] MIME string returned to caller, on return, filled with a pointer to a 


constant string (do not free) 


Return Value: 
SUCCESS: Data type is detected and MIME is returned 
ENOTYPE: There is no type associated with this data 
EBADPARM: Wrong input data (parameter(s)) 


ENEEDMORE: Need more data to perform type detection. *pdwSize contains the the 
required number of additional bytes. 


EUNSUPPORTED: Type detection for the specified input is not supported 


Comments: 
pBuf takes precedence over pszName. If both of them are specified, then first pBufis 
used for type detection followed by pszName. 


If the function returns ENEEDMORE, then *pdwSize is filled with the required 
additional bytes to carry out the operation. Call this function again with (original dwSize 
+ *pdwSize) bytes. 

To determine the maximum number of bytes required to enable type detection, you can 
call 
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brew. 
if (ENEEDMORE == ISHELI DetectType (ps, NULL, &dwRegSize, NULL, 
NULL) ) 
t 
// dwRegSize contains the max bytes needed for type detection 
) 
IMPORTANT NOTE TO OEMs: 
(1) Do not modify the existing type detection code. 
(2) Add your new type detection functions and you may order them accordingly. 
See Also: 


ISHELL DetectType() 
ISHELL GetHandler() 
ISHELL CreateInstance() 
Return to the List of functions 
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OEM Operating System 
Interface 


This section describes the functions in the OEM Operating System Interface. 


List of functions 


Functions in this interface include: 


OEMOS ActiveTaskID() 
OEMOS BrewHighPriority() 
OEMOS BrewNormalPriority() 
OEMOS CancelDispatch() 
OEMOS GetLocalTime() 
OEMOS GetTimeMS() 
OEMOS GetUptime() 
OEMOS LocalTimeOffset() 
OEMOS SetTimer() 
OEMOS SignalDispatch() 
OEMOS Sleep() 


The remainder of this section provides details for each function. 
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OEMOS ActiveTaskID() 


Description: 
This function returns the ID of the currently running task. 


Prototype: 


uint32 OEMOS ActiveTaskID (void) 





Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMOS BrewHighPriority() 


Description: 


This function raises BREW's task priority so that certain time-limited operations (such 
as signature verification) will be performed more quickly. 


Prototype: 


void OEMOS BrewHighPriority (void) 





Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 


631 


Eri OEM Operating System Interface 


OEMOS BrewNormalPriority() 


Description: 
This function return BREW's task priority to its normal level. 


Prototype: 


void OEMOS BrewNormalPriority (void) 





Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMOS CancelDispatch() 


Description: 


If there is an event in the queue to call AEE DISPATCH, this function sets its enable 
field to FALSE so that AEE DISPATCH will not be called. If such an event does not 
exist, one is created. This is OK because the event will have its enable set to FALSE 
so it will be ignored by the event handler. 


Prototype: 


void OEMOS CancelDispatch (void) 





Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMOS GetLocalTime() 


Description: 
This function returns the current time in seconds since 1/6/1980. 


Prototype: 


uint32 OEMOS GetLocalTime (void) 





Parameters: 
None 


Return Value: 
The current time in seconds since 1/6/1980. 


Comments: 


The time returned by this function can change when the device acquires time from a 
network. Therefore, do not assume that each call to this function will return a greater 
value. 


Even though this function returns the current time in seconds, the accuracy of that time 
is determined by the time resolution of the underlying hardware/software platform. 


See Also: 
OEMOS GetTimeMS() 
OEMOS GetUptime() 
Return to the List of functions 
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OEMOS GetTimeMS() 


Description: 
This function returns the number of milliseconds since midnight. 


Prototype: 


uint32 OEMOS GetTimeMS (void) 





Parameters: 
None 


Return Value: 
The number of milliseconds since midnight. 


Comments: 


The time returned by this function can change when the device acquires time from a 
network. Therefore, do not assume that each call to this function will return a greater 
value. 


Even though this function returns the current time in milliseconds, the accuracy of that 
time is determined by the time resolution of the underlying hardware/software platform. 


See Also: 
OEMOS GetLocalTime() 
OEMOS GetUptime() 
Return to the List of functions 


635 


Eri OEM Operating System Interface 


OEMOS GetUptime() 


Description: 
This function returns the time in milliseconds since the device started. 


Prototype: 


uint32 OEMOS GetUptime (void) 





Parameters: 
None 


Return Value: 
The time in milliseconds since the device started. 


Comments: 


If a device is tumed on for approximately 50 days, this value can roll over and restart 
at zero. 


See Also: 
OEMOS GetLocalTime() 
OEMOS GetTimeMS() 
Return to the List of functions 
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OEMOS LocalTimeOffset() 


Description: 
This function returns the local time zone offset from UTC, in seconds. It optionally 
returns a flag indicating that daylight savings time is active. ifitis active, the value of 
the local time zone offset already takes the shift into account, and the flag controls the 
display of a time zone name. 


The returned value is added to UTC to give the local time, or subtracted from the local 
time to give the UTC time. 





Prototype: 
int32 OEMOS LocalTime0Offset (boolean * DaylightSavings) 
Parameters: 
DaylightSavings ' Pointerto boolean, which is set to TRUE if daylight savings time is 


active. 


Return Value: 
The local time zone offset from UTC in seconds. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMOS SetTimer() 


Description: 


This function sets the master OEM timer to nMSecs milliseconds. After nMSecs, the 
OEM code will callthe AEE TimerExpired() function. A callto OEMOS SetTimer while 
another timer is still pending will cancel the previous timer before setting the new one. 
A callto OEMOS SetTimer with an nMSecs value of O will cancel the pending timer, 
if one is active. 


Prototype: 


void OEMOS SetTimer (uint32 nMSecs) 





Parameters: 


nMSecs Number of milliseconds to set the master OEM timer. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMOS SignalDispatch() 


Description: 


This function adds an event to the event queue that will cause AEE DISPATCH to be 
called. 


Prototype: 


void OEMOS SignalDispatch (void) 





Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMOS Sleep() 


Description: 


This function delays execution of subsequent code for nMSecs milliseconds. It will 
block for nMSecs. 





Prototype: 

void OEMOS Sleep (uint32 nMSecs) 
Parameters: 

nMSecs Number of milliseconds to sleep. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Random Number 
Generator Interface 


This interface provides all of the basic routines for Random Number Generation. 


List of functions 


Functions in this interface include: 


OEMRan GetNonPseudoRandomBytes() 
OEMRan Next() 
OEMRan Seed() 


The remainder of this section provides details for each function. 
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OEMRan GetNonPseudoRandomBytes() 


Description: 
Return 20 bytes of crypto quality random data. This routine need not return new 
random data more than about once every 100ms. If you don't have a source of pure 
random numbers, fill the buffer with zeros and return. 





Prototype: 

void OEMRan GetNonPseudoRandomBytes (byte *pbRand, int *pcbLen); 
Parameters: 

pbRand buffer to fill with random data 

pcbLen length of buffer on input, length of random data on output 


Return Value: 
None 


Comments: 


Brew internally produces cryptographic quality random numbers using key stroke and 
network timing and randomness in the memory manager. However if an additional very 
high quality source of randomness is available it can be fed in to the pool here. A good 
example would be noise taken of the phone antenna. A bad example would be 
randomness from key strokes or time. 

If you have more good random data, return it 20 bytes at a time when called here. If 
the pool you have is larger than 20 bytes, used SHA-1 or MDS to reduce it to 20 bytes. 
If you don't have good random data this should return a buffer of zeros. 

No concern should be given here for accumulating or stirring the random pool. This is 
all handled internally. 


See Also: 
None 


Return to the List of functions 
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OEMRan Next() 


Description: 
This function returns the next number in the sequence 


Prototype: 


uint32 OEMRan Next (void) 





Parameters: 
None 


Return Value: 
The next number in the sequence 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMRan Seed() 


Description: 
This function seeds the random number generator. 


Prototype: 


void OEMRan Seed (uint32 seed) 





Parameters: 


seed Seed value for the random number generator. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM SMS Interface 


This section describes the SMS Interface functions that the AEE files use to provide Short 
Message Service functionality to BREW applications. 


List of Functions 


Functions in this interface include: 


OEM extract SMS text() 

OEM format SMS msg() 

OEM format SMS text() 

OEM uasms config listeners() 


The remainder of this section provides details for each function. 
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OEM extract SMS text() 


Description: 


This function extracts text ffom the SMS message. This routine is necessary because 
OEMs in some markets choose to decode into an alternate format that is more 
appropriate for the type of SMS supported. 


Prototype: 


AEESMSTextMsg * OEM extract SMS text 

( 

const uasms user data type * pm, 
byte * pDest, 

int nSize 


) 














Parameters: 
pm Input SMS message (user data). 
pDest Buffer to hold the text extracted from the SMS message. 
nSize Size of the destination buffer. 


Return Value: 
Final formatted SMS text if successful. 
NULL if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of Functions 
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OEM format SMS msg() 


Description: 


This function extracts AEESMSMsg from the SMS message. This routine is necessary 
because OEMs in some markets choose to decode into an alternate format that is 
more appropriate for the type of SMS supported. 


Prototype: 


void OEM format SMS msg 

( 

uasms teleservice e type ts, 

const uasms client bd type * pData, 
AEESMSMsg * pm 
) 

















Parameters: 
ts Teleservice type. 
pData Input SMS data. 
pm Formatted SMS message. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of Functions 
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OEM format SMS text() 


Description: 
This function formats SMS text given the buffer, length, and encoding. 


Prototype: 


AEESMSTextMsg * OEM format SMS text 
( 
byte * pMsgData, 

int nMsgLen, 

uasms user data encoding e type encoding, 
byte * pDest, 

int nSize 


) 

















Parameters: 


pMsgData Input SMS text string. 

nMsgLen Input SMS text string length. 
encoding Encoding type. 

pDest Buffer to hold the formatted SMS text. 
nSize Size of the destination buffer. 


Return Value: 
Final formatted SMS text if successful. 
NULL if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of Functions 
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OEM SMS Interface 


OEM uasms config listeners() 


Description: 


This function registers OEM SMS notification functions to the AEE. 


Prototype: 





void OEM uasms config listeners 


( 


uasms message listener type pÍnMsg, 
uasms status listener type pfÍnStatus, 
uasms event listener type pfnEvent 


) 


Parameters: 


pfnMsg 
pfnStatus 
pfnEvent 


Return Value: 


None 


Comments: 
None 


See Also: 
None 





Message listener function pointer. 
Status listener function pointer. 
Event listener function pointer. 


Return to the List of Functions 
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OEM Socket Interface 


The OEM Socket interface provides standard internet socket support. The semantics are 
modeled after BSD style sockets, but are strictly non-blocking. If an operation is unable to 
complete immediately, it should retum an error code of AEE NET EWOULDBLOCK. BREW 
willthen use OEMSocket AsyncSelect() to indicate interest in an event for a particular socket. 
When the event occurs, call AEE SocketEventOccurred, and BREW will in tum use 
OEMSocket GetNextEvent() to determine which specific event has occurred for that socket. 


The following functions are encouraged, but are optional and may return an error code of 
AEE NET EOPNOTSUPP: 


OEMSocket Accept() 
OEMSocket Listen() 
OEMSocket Shutdown() 


List of functions 


Functions in this interface include: 


OEMSocket Accept() 
OEMSocket AsyncSelect() 
OEMSocket Bind() 
OEMSocket Close() 
OEMSocket Connect() 
OEMSocket GetNextEvent() 
OEMSocket GetPeerName() 
OEMSocket GetSockName() 
OEMSocket Listen() 
OEMSocket Open() 
OEMSocket Read() 
OEMSocket Readv() 
OEMSocket RecvFrom() 
OEMSocket SendTo() 
OEMSocket Shutdown() 
OEMSocket Write() 
OEMSocket Writev() 


The remainder of this section provides details for each function. 
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OEMSocket Accept() 


Description: 


The accept function is used on listening sockets to respond when 

AEE NET READ EVENT is asserted. The first backlog queued connection is 
removed from the queue, and bound to a new socket (as if you called 

OEMSocket Open). The newly created socket is in the connected state. The listening 
socket is unaffected and the queue size is maintained (i.e. there is no need to call listen 
again.) 


Prototype: 


OEMCONTEXT OEMSocket Accept 
( 




















EMCONTEXT sockd, 
nt1l6 *err 








O 
i 
) . 


r 


Parameters: 
sockd listening socket descriptor 
err error code (returned by operation) 


Return Value: 


On successful creation of a socket, this function returns socket descriptor which is 
OEM defined. 


On error, returns AEE NET ERROR. Error specifics are returned via the err 
parameter. 


Comments: 
None 


See Also: 
OEMSocket Listen() 
Return to the List of functions 
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OEMSocket AsyncSelect() 


Description: 


This function enables the events to be notified about through the asynchronous 
notification mechanism. The application specifies a bitmask of events in which it is 
interested, for which it will receive asynchronous notification by its application callback 
function. 


This function also performs a real-time check to determine if any of the events have 
already occurred, and if so, itinvokes the application callback. 


Events OEMs need to support are: 
AEE NET READ EVENT: Socket is now available to read or connect 
AEE NET WRITE EVENT: Socket is now available for writing 
AEE NET CLOSE EVENT: Socket is being closed 

















Prototype: 

int16 OEMSocket AsyncSelect (OEMCONTEXT sockd, int32 interest mask) 
Parameters: 

sockd Socket descriptor. 

mask Bitmask of events to set (see above). 


Return Value: 
AEE NET SUCCESS, if successful. 
AEE designated error code, if there is a failure. 


Comments: 
None 


Side Effects: 


The application will be notified using the callback function. 


See Also: 
None 
Return to the List of functions 
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OEMSocket Bind() 


Description: 
For all client sockets, this function attaches a local address and port value to the 
socket. If the call is not explicitly issued, the socket implicitly binds during calls to 
OEMSocket Connect() or OEMSocket SendTo(). 
NOTE: This function does not support binding a local IP address, but only a local port 
number. 
The local IP address is assigned automatically by the sockets library. The function 
must receive (as a parameter) a valid socket descriptor, implying a previous successful 
call to OEMSocket Open(). 


This function is synchronous, and therefore should not callback any notification 

















functions. 
Prototype: 

int16 OEMSocket Bind (OEMCONTEXT sockd, INAddr addr, INPort port) 
Parameters: 

sockd Socket descriptor. 

addr Local address in network byte order. 

port Local port in network byte order. 


Return Value: 
AEE NET SUCCESS, if successful. 
AEE designated error code, if there is a failure. 


Comments: 
None 


See Also: 
INAddr 
INPort 
Return to the List of functions 
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OEMSocket Close() 


Description: 


This function performs a non-blocking close of a socket, and performs all necessary 
clean-up of data structures and frees the socket for re-use. For TCP, it initiates the 
active close for connection termination. After the TCP connection is complete, the 
socket resources may optionally not be freed. In this case, this function should return 
AEE NET ERROR and seterr to AEE NET EWOULDBLOCK. The AEE libraries 
receive notification through OEMSocket AsyncSelect() and call OEMSocket Close() 
again to free the resources. 


This function can be synchronous (returning anything other than *err set to 

AEE NET EWOULDBLOCK), or asynchronous as described above. For 
asynchronous incantations, AEE SocketEventOccurred() should be called only if the 
AEE NET CLOSE EVENT was registered with OEMSocket AsyncSelect(). 

















Prototype: 

int 16 OEMSocket Close (OEMCONTEXT sockd) 
Parameters: 

sockd Socket descriptor. 


Return Value: 
AEE NET SUCCESS, if successful. 


AEE designated error code, if there is a failure. If the socket cannot be closed right 
away, the OEM may retum an AEE NET EWOULDBLOCK error, indicating that it 
should be called at a later time (through an indication ffom OEMSocket AsyncSelect(). 


Comments: 
None 


Side Effects: 


Initiates active close for TCP connections. 


See Also: 
OEMSocket AsyncSelect() 
Return to the List of functions 
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OEMSocket Connect() 


Description: 
For TCP, this function attempts to establish the TCP connection. Upon successful 
connection, it calls the socket callback function 
This function is asynchronous and should call AEE NetEventOccurred() if the 


connection attempt is completed or aborted, and the original error value was 
AEE NET SUCCESS. 

















Prototype: 

int16 OEMSocket Connect (OEMCONTEXT sockd, INAddr addr, INPort port) 
Parameters: 

sockd Socket descriptor. 

addr Destination address in network byte order. 

port Destination port in network byte order. 


Return Value: 


AEE NET SUCCESS, if arguments are valid, and the connection process could be 
started. Thus, a retum value ofAEE NET SUCCESS does not indicate that the socket 
could be connected. 


AEE designated error code, if there is a failure or an error can be detected immediately 


Comments: 
None 


Side Effects: 


This function starts the connection process for a socket. It may automatically call bind() 
on that socket. 


See Also: 
INAddr 
INPort 
Return to the List of functions 
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OEM Socket Interface 


OEMSocket GetNextEvent() 


Description: 


This function performs a real-time check to determine if any of the events of interest 
specified with the mask in OEMSocket AsyncSelect() have occurred. It also clears any 
bits in the event mask that have occurred. The application must re-enable these events 
through a subsequent callto OEMSocket AsyncSelect(). It may pass a pointer to a 
single socket descriptor to determine if any events have occurred for that socket. 
Alternatively, the application may set this pointer's referenced value to NULL (0). 


NOTE: Do not confuse the referenced value of NULL (0) with a NULL pointer. NULL 
(0) is a pointer referencing an address with a value of O (zero), in which case the 
function returns values for the next available socket. 


The next available socket's descriptor is to be placed in the socket descriptor pointer, 
and the function will return. Ifno sockets are available (no events have occurred across 
all sockets for that application) the pointer value remains NULL (original value passed 
in), and the function returns O, indicating that no events have occurred. 




















Prototype: 

int32 OEMSocket GetNextEvent (OEMCONTEXT * sockd, intl6 * err) 
Parameters: 

sockd Socket descriptor. 

err Error code retumed by operation. 


Return Value: 


Returns an event mask of the events that were asserted. A value of zero indicates that 
no events have occurred. 


On passing a pointer whose value is NULL into the function for the socket descriptor 
(not to be confused with a NULL pointer), this function places the next available socket 
descriptor in *sockd and returns the event mask for that socket. If no sockets are 
available (no events have occurred across all sockets for that application) the pointer 
value remains NULL (original value passed in), and the function returns zero indicating 
that no events have occurred. On error, returns AEE NET ERROR. 


Comments: 


None 


See Also: 


OEMSocket AsyncSelect() 
Return to the List of functions 
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OEMSocket GetPeerName() 


Description: 
This function returns the IP address and port of a connected peer.The address and port 
are in network byte order. This function is synchronous, and therefore must not callany 
notification functions. 














Prototype: 
intl6 OEMSocket GetPeerName 
( 
OEMCONTEXT sockd, 
INAddr *addr, 
INPort *port 
); 
Parameters: 
sockd [in] Socket descriptor 
addr [out] IP address 
port [out] Port number 


Return Value: 


On success, returns AEE NET SUCCESS. On error, returns one of the AEE 
designated error codes indicating reason for failure. 


Comments: 
None 


See Also: 
INAddr 
INPort 
Return to the List of functions 
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OEMSocket GetSockName() 


Description: 


Returns the local IP address and port of a socket. The address and port will be in 
network byte order. 


This function is synchronous, and therefore must not call any notification functions. 


Prototype: 


int 16 OEMSocket, GetSockName 











NAddr *addr, 
NPort *port 


r 





O 
( 
OEMCONTEXT sockd, 
I 
1 
) 


Parameters: 
sockd [in] socket descriptor 
addr [out] IP address 
port [out] port number 


Return Value: 
On success, returns AEE NET SUCCESS. 
On error, returns one of the AEE designated error codes indicating reason for failure. 


Comments: 
None 


See Also: 
INAddr 
INPort 
Return to the List of functions 
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OEMSocket Listen() 


Description: 


Performs a passive open for connections, such that incoming connections may be 
subsequently accepted. The socket must be a TCP socket that has been bound to a 
local port. The backlog parameter indicates the maximum length for the queue of 
pending connections. If backlog is larger than the system maximum, it will be silently 
reduced to the system maximum. 


Prototype: 


int 16 OEMSocket Listen 














nt16 backlog 


K 


O 
( 
OEMCONTEXT sockd, 
i 
) 


Parameters: 
sockd socket descriptor 
backlog maximum number of pending connections 


Return Value: 
On success, returns AEE NET SUCCESS. 
On error, returns one of the AEE designated error codes indicating reason for failure. 


Comments: 
None 


See Also: 
OEMSocket Accept() 
Return to the List of functions 
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OEMSocket Open() 


Description: 


This function creates a TCP or UDP socket and related data structures, and returns a 
reference to that socket. 


Supported Types: 


The OEM must support the SOCK STREAM (TCP) and SOCK DGRAM (UDP) data 
types. This function must be called to obtain a valid socket descriptor for use with all 
other socket-related functions. Before any socket functions can be used (such as I/O, 
asynchronous notification, and so on), this call must have successfully returned a valid 
socket descriptor. 

This function is synchronous, and therefore should not callback any notification 
function. 


Prototype: 


OEMCONTEXT OEMSocket Open (NetSocket type, intl6 * err) 




















Parameters: 


type Socket type (see above). 
err Error code (returned by operation). 


Return Value: 


On successful creation of a socket, this function returns socket file descriptor that is a 
signed value greater than or equal to O (zero). 


On error, returns AEE NET ERROR. Error specifics are retumed via the err 
parameter. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMSocket Read() 


Description: 


This function reads the specified number of bytes into the buffer from the TCP 
transport. If the socket is connected but there is no data to read, the function should 
return AEE NET ERROR and set*err to AEE NET EWOULDBLOCK. 


Prototype: 


int32 0OEMSocket Read 
( 
OEMCONTEXT sockd, 
byte * buffer, 
uint32 nbytes, 
intl6 * err 


) 














Parameters: 
sockd Socket descriptor. 
buffer User buffer to which to copy data. 
nbytes Maximum number of bytes to be read from socket. 
err Error code (returned by operation). 


Return Value: 


On success, returns the number of bytes read, which could be less than the number of 
bytes specified. 


On error, returns AEE NET ERROR, including when *err is 
AEE NET EWOULDBLOCK. 


NOTE: A return of O (zero) indicates that an End-of-File (EOF) condition has occurred. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMSocket Readv() 


Description: 


This function provides the scatter read variant of OEMSocket Read(), which allows the 
application to read into non-contiguous buffers. It reads the specified number of bytes 
into the buffer from the TCP transport. 


Prototype: 


int32 0OEMSocket Readv 
( 
OEMCONTEXT sockd, 
SockIOBlock iovll, 
uint1l6 iovcount, 
intl6 * err 


) 














Parameters: 
sockd Socket descriptor. 
iov Array of data buffers to which to copy data. 
iovcount Number of array items. 
err Error code (returned by operation). 


Return Value: 


On success, returns the number of bytes read, which could be less than the number of 
bytes specified. 


On error, returns AEE NET ERROR. 
NOTE: A return of O (zero) indicates that an End-of-File (EOF) condition has occurred. 


Comments: 
None 


See Also: 
SockIOBlock 
Return to the List of functions 
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OEMSocket RecvFrom() 


Description: 


This function reads nbytes bytes in the buffer ffom the UDP transport. It fills in the 
address and port pointers with values from who sent the data. 


Prototype: 


int32 0OEMSocket RecvFrom 
( 
OEMCONTEXT sockd, 
byte * buffer, 
uint32 nbytes, 
uintl6 flags, 
INAddr * addr, 
INPort * port, 
intl6 * err 


) 














Parameters: 
sockd Socket descriptor. 
buffer User buffer into which to copy data. 
nbytes Number of bytes to be read. 
flags 
addr IP address, in network byte order. 
port Port number, in network byte order. 
err Error condition value. 


Return Value: 
Number of bytes read. Can be less than the number of bytes specified. 
AEE NET ERROR, if there is an error. 


Comments: 
None 


See Also: 
INAddr 
INPort 
Return to the List of functions 
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OEMSocket SendTo() 


Description: 
This function sends nbytes bytes in the buffer over the UDP transport. 


Prototype: 


int32 0OEMSocket SendTo 
( 
OEMCONTEXT sockd, 
const byte * buffer, 
uint32 nbytes, 
uintl6 flags, 

INAddr addr, 

INPort port, 

intl6 * err 


) 














Parameters: 
sockd Socket descriptor. 
buffer User buffer from which to copy the data. 
nbytes Number of bytes to be written. 
flags send flags 
addr IP address, in network byte order. 
port Port number, in network byte order. 
err Error condition value. 


Return Value: 
Number of bytes written. Can be less than the number of bytes specified. 
AEE NET ERROR, if there is an error. 


Comments: 
Currently supported flags are documented in AEENet.h. 


For cdma2000, the URGENT flag corresponds to use of Short Data Burst (SDB) over 
the reversed enhanced access channel (R-EACH). The WAKEUP flag requests traffic 
channel origination immediately after the SDB attempt. This is necessary because the 
cdma2000 standard currently requires origination to take priority over any other access 
attempt, and thus the short data burst would either be prematurely aborted or 
undesirably delayed. 


See Also: 
INAddr 
INPort 
Return to the List of functions 


664 


Eri OEM Socket Interface 


OEMSocket Shutdown() 


Description: 
Causes all or part of a full-duplex connection to be terminated gracefully. 


fhow is AEE SHUTDOWN RD, no more reads will be allowed. If how is 
AEE SHUTDOWN WR, no more writes will be allowed (AKA half-close). If how is 
AEE SHUTDOWN RDWR, both read and write will be disallowed. 


Prototype: 


int 16 OEMSocket. Shutdown 














O 
( 
OEMCONTEXT sockd, 
int32 how 

) 


r 


Parameters: 
sockd socket descriptor 
how dictates which portion(s) of the connection to shutdown 


Return Value: 
On success, returns AEE NET SUCCESS. 


On error, returns one of the AEE designated error codes (including 
AEE NET WOULDBLOCK) indicating reason for failure. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMSocket Write() 


Description: 
This function sends a specified number of bytes in the buffer over the TCP transport. 


Prototype: 


int32 0OEMSocket Write 
( 
OEMCONTEXT sockd, 
const byte * buffer, 
uint32 nbytes, 

intl6 * err 


) 














Parameters: 
sockd Socket descriptor. 
buffer User buffer from which to copy data. 
nbytes Number of bytes to be written to socket. 
err Error condition value. 


Return Value: 
Number of bytes written. Can be less than the number of bytes specified. 


AEE NET ERROR, if there is an error; places one of the following error condition 
values in err: 


DS EBADF: Invalid socket descriptor is specified. 

DS ENOTCONN: Socket not connected. 

DS ECONNRESET: TCP connection reset by server. 

DS ECONNABORTED: TCP connection aborted due to timeout or other failure. 
DS EIPADDRCHANGED: IP address changed, causing TCP connection reset. 
DS EPIPE: Broken pipe. 

DS EFADDRREQ: Destination address required; 

DS ENETDOWN: Network subsystem unavailable. 

DS EFAULT: Application buffer no valid part of address space. 

DS EWOULDBLOCK: Operation would block. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEMSocket Writev() 


Description: 


This function provides the gather write variant of the OEMSocket Write() function, 
which allows the application to write ftom non-contiguous buffers. It sends a specified 
number of bytes in the buffer over the TCP socket. 


Prototype: 


int32 0OEMSocket Writev 
( 
OEMCONTEXT sockd, 

const SockIOBlock iovl[], 
uint1l6 iovcount, 

intl6 * err 


) 














Parameters: 
sockd Socket descriptor. 
iov Array of data buffers from which to copy data. 
iovcount | Number of array items. 
err Error condition value. 


Return Value: 
Written number of bytes. Can be less than the specified number of bytes. 


AEE NET ERROR, if there is an error; places one of the following error condition 
values in err: 


DS EBADF: Invalid socket descriptor is specified. 

DS ENOTCONN: Socket not connected. 

DS ECONNRESET: TCP connection reset by server. 

DS ECONNABORTED: TCP connection aborted due to timeout or other failure. 
DS EIPADDRCHANGED: IP address changed, causing TCP connection reset. 
DS EPIPE: Broken pipe. 

DS EFADDRREQ: Destination address required. 

DS ENETDOWN: Network subsystem unavailable. 

DS EFAULT: Application buffer no valid part of address space. 

DS EWOULDBLOCK: Operation would block. 


Comments: 
None 


See Also: 
SockIOBlock 
Return to the List of functions 
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OEM Sound Interface 


This section describes the Sound Interface functions that the AEE uses to provide a simple 
way to play multi-tones, generate vibration, and set the device volume. 


List of functions 


Functions in this interface include: 


OEMSound Deletelnstance() 
OEMSound GetLevels() 
OEMSound GetVolume() 
OEMSound Init() 
OEMSound Newlnstance() 
OEMSound PlayFregTone() 
OEMSound PlayTone() 
OEMSound PlayToneList() 
OEMSound SetDevice() 
OEMSound SetVolume() 
OEMSound StopTone() 
OEMSound StopVibrate() 
OEMSound Vibrate() 


The remainder of this section provides details for each function. 
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OEMSound Deletelnstance() 


Description: 


This function decreases ref count of underlying audio device and gives an opprtunity 
to restore the default settings when ref count goes to zero. 


Prototype: 


int OEMSound NewInstance (AEESoundInfo * psi); 














Parameters: 
psi [in]: Sound info of the ISound object 


Return Value: 
SUCCESS if successful. 
Error code otherwise. 


Comments: 
This function is called every time an instance of ISound is deleted. 


See Also: 
OEMSound Newlnstance() 
Return to the List of functions 
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OEMSound GetLevels() 


Description: 


This function returns the number of volume levels supported for the device/class pair. 
Itis called when a user issues ISOUND GetVolume() or ISOUND SetVolume(). 














Prototype: 

void OEMSound GetLevels (AEESoundInfo * psi, void * pUser) 
Parameters: 

psi Sound device information. See the BREW API Reference Guide for the 


definition of AEESoundinfo. 


pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound LevelCB is called with the result. 


See Also: 
None 
Return to the List of functions 
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OEMSound GetVolume() 


Description: 
This function issues a command to get the volume level of device/class pair. 

















Prototype: 

void OEMSound GetVolume (AEESoundInfo * psi, void * pUser) 
Parameters: 

psi Sound device information. See the BREW API Reference Guide for the 


definition of AEESoundinfo. 


pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound VolumeCB is called with the result. 


See Also: 
None 
Return to the List of functions 
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OEMSound Init() 


Description: 
Maps device sound layer enumerations to AEE SOUND enumerations. 


Prototype: 
void OEMSound Init( void ); 


Parameters: 
None 


Return Value: 
None 


Comments: 
This function is called only once during BREW initialization. 


See Also: 
None 
Return to the List of functions 
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OEMSound Newlnstance() 


Description: 


This function increases ref count of underlying audio device. It returns current 
AEESoundinfo. 














Prototype: 

int OEMSound NewInstance (AEESoundInfo * psi); 
Parameters: 

psi [out] Current sound info 


Return Value: 
SUCCESS if successful. 
Error code otherwise. 


Comments: 
This function is called every time an instance of ISound is created. 


See Also: 
OEMSound Deletelnstance() 
Return to the List of functions 
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OEMSound PlayFregTone() 


Description: 
This function issues a command to play a specified pair of tone frequencies. 


Prototype: 


void OEMSound PlayFregTone 











» — 


EESoundInfo * psi, 
uintl6 wHiFreg, 
uint1l6 wLoFreg, 
uint16 wDuration, 
void * pUser 


) 








Parameters: 


psi Sound device information. See the BREW API Reference Guide for the 
definition of AEESoundlnfo. 


wHiFrteeq High frequency of the specified pair of tone frequencies. 


wLoFreg Low frequency of the specified pair of tone frequencies. 

wDuration Duration of the tone play. 

pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound StatusCB is called with the status. 


See Also: 
None 
Return to the List of functions 
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OEMSoun 


Description: 


OEM Sound Interface 


d PlayTone() 


This function issues a command to play a specified tone. 


Prototype: 


void OE 
( 





Sound PlayTone 





EESoundInfo * psi, 








A 
A 











Vo 


) 


Parameters: 
psi 


toneData 
pUser 


EESoundToneData toneData, 


id * pUser 


Sound device information. See the BREW API Reference Guide for the 
definition of AEESoundinfo. 


Tone and duration to be played. 


User data that is passed back to the caller through the status callback 
function. 


Return Value: 


None 


Comments: 
None 


Side Effects: 


AEESound StatusCB is called with the status. 


See Also: 
None 
Return to 


the List of functions 
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OEMSound PlayToneList() 


Description: 
This function issues a command to play a list of tones. 


Prototype: 


void OEMSound PlayToneList 
( 








AEESoundInfo * psi, 
AEESoundToneData * pToneData, 
uint16 wDataLen, 

void * pUser 


) 

















Parameters: 


psi Sound device information. See the BREW API Reference Guide for the 
definition of AEESoundinfo. 

pToneData An array of tones and durations. 

wDataLen Number of tones and durations. 

pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound StatusCB is called with the status. 


See Also: 
None 
Return to the List of functions 
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OEMSound SetDevice() 


Description: 
This function issues a command to set the sound output device. 

















Prototype: 

void OEMSound SetDevice (AEESoundInfo * psi, void * pUser) 
Parameters: 

psi New sound device information. See the BREW API Reference Guide for the 


definition of AEESoundinfo. 


pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound StatusCB is called with the status. 


See Also: 
None 
Return to the List of functions 
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Eri OEM Sound Interface 


OEMSound SetVolume() 


Description: 
This function issues a command to set the volume of a sound device/class pair. 


Prototype: 


void 0OEMSound SetVolume 
( 











AEESoundInfo * psi, 
uint1l6 wLevel, 
void * pUser 


) 








Parameters: 
psi Sound device information. See the BREW API Reference Guide for the 
definition of AEESoundinfo. 
wLevel New volume for the device. 
pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound VolumeCB is called with the result. 


See Also: 
None 
Return to the List of functions 
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OEMSound StopTone() 


Description: 
This function issues a command to stop playing a single tone or playlist. 





Prototype: 
void OEMSound StopTone (boolean bPlayList, void * pUser) 
Parameters: 
bPlayList Flag that stops playing a tone list playback. 
pUser User data that is passed back to the caller through the status callback 
function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound StatusCB is called with the status. 


See Also: 
None 
Return to the List of functions 
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OEMSound StopVibrate() 


Description: 


This function stops the current vibration. If the feature is not supported, it does not do 
anything. 


Prototype: 


void OEMSound StopVibrate (void * pUser) 





Parameters: 


pUser User data that is passed to the caller through the status callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound StatusCB is called with the status. 


See Also: 
None 
Return to the List of functions 
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Eri OEM Sound Interface 


OEMSound Vibrate() 


Description: 


This function causes the device to vibrate for the specified amount to time. If the 
feature is not supported, it does not do anything. 





Prototype: 

void OEMSound Vibrate (uint1l6 wDuration, void * pUser) 
Parameters: 

wDuration Duration of vibration in milliseconds. 

pUser User data that is passed to the caller through the status callback 


function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 
AEESound StatusCB is called with the status. 


See Also: 
None 
Return to the List of functions 
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OEM SoundPlayer Interface 


This section describes the multimedia SoundPlayer Interface functions that the AEE uses to 
provide controls for a basic sound player. 


List of functions 


Functions in this interface include: 


OEMSoundPlayer FastForward() 
OEMSoundPlayer GetTotalTime() 
OEMSoundPlayer Pause() 
OEMSoundPlayer Play() 
OEMSoundPlayer PlayRinger() 
OEMSoundPlayer Resume() 
OEMSoundPlayer Rewind() 
OEMSoundPlayer Stop() 
OEMSoundPlayer Tempo() 
OEMSoundPlayer Tune() 


The remainder of this section provides details for each function. 
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Era OEM SoundPlayer Interface 


OEMSoundPlayer FastForward() 


Description: 


This function issues a command to fast forward an audio the indicated number of 
milliseconds. 


Prototype: 


void OEMSoundPlayer FastForward (uint32 dwTime, void * pUser) 





Parameters: 


dwTime Number of milliseconds to fast forward. 
pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 


It must also trigger to call AEESoundPlayer PlayCB with 
AEE SOUNDPLAYER FFORWARD. 


See Also: 
OEMSoundPlayer Pause() 
OEMSoundPlayer Resume() 
OEMSoundPlayer Rewind() 
Return to the List of functions 
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Era OEM SoundPlayer Interface 


OEMSoundPlayer GetTotalTime() 


Description: 
This function issues a command to calculate the time of the indicated audio file. 


Prototype: 


void OEMSoundPlayer GetTotalTime 
( 














AEESoundPlayerInput * pInfo, 
void * pUser 


) 





Parameters: 


pInfo SoundPlayer source data. 
pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer TimeCB is called with the command status and time information if 
the command was successfully performed. It can be one of the following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 


See Also: 
None 
Return to the List of functions 
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OEMSoundPlayer Pause() 


Description: 
This function issues a command to pause an audio playback. 


Prototype: 


void 0OEMSoundPlayer Pause (void * pUser) 





Parameters: 


pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 
It must also call AEESoundPlayer PlayCB with AEE SOUNDPLAYER PAUSE. 


See Also: 
OEMSoundPlayer Resume() 
Return to the List of functions 
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Era OEM SoundPlayer Interface 


OEMSoundPlayer Play() 


Description: 
This function issues a command to play an audio file. 

















Prototype: 

void OEMSoundPlayer Play (AEESoundPlayerInput * pInfo, void * pUser) 
Parameters: 

pInfo SoundPlayer source data. 


pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer PlayCB is called with the current audio play. There must be at least 
one callback when this function executed with one of the following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 


f AEE SOUNDPLAYER SUCCESS is sent back, one of the following status codes 
must be sent back at some time before the next play: 


AEE SOUNDPLAYER DONE 
AEE SOUNDPLAYER ABORTED 


For other operations, the current play also triggers a callback to inform the client of the 
play status. 


See Also: 
OEMSoundPlayer FastForward() 
OEMSoundPlayer Pause() 
OEMSoundPlayer Resume() 
OEMSoundPlayer Rewind() 
OEMSoundPlayer Stop() 
Return to the List of functions 


686 


brew. 


OEM SoundPlayer Interface 


OEMSoundPlayer PlayRinger() 


Description: 


This function issues a command to play a MIDI ringer. 


Prototype: 


void OE 
( 





SoundPlayer PlayRinger 








AE 


ESoundPlayerinfo * pInfo, 








uintl6 wRepeatTimer, 
void * pUser 


) 


Parameters: 
pInfo 


SoundPlayer source data. 


wRepeatTimer | Time, in milliseconds, of the silence between the playbacks of the 


pUser 


MIDI file. Playback is not repeated if this is set to O (zero). 
Client data to be sent back with the callback function. 


Return Value: 


None 


Comments: 
None 


Side Effects: 


AEESoundPlayer PlayCB is called with the current audio play. There must be at least 
one callback when this function executed with one of the following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 


f AEE SOUNDPLAYER SUCCESS is sent back, one of the following status codes 
must be sent back at some time before the next play: 


AEE SOUNDPLAYER DONE 
AEE SOUNDPLAYER ABORTED 


See Also: 


OEMSoundPlayer Stop() 


Return to 


the List of functions 
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OEMSoundPlayer Resume() 


Description: 
This function issues a command to resume MIDI or WebAudio playback. 


Prototype: 


void OEMSoundPlayer Resume (void * pUser) 





Parameters: 


pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 
It must also call AEESoundPlayer PlayCB with AEE SOUNDPLAYER RESUME. 


See Also: 
OEMSoundPlayer Pause() 
Return to the List of functions 
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Eri OEM SoundPlayer Interface 


OEMSoundPlayer Rewind() 


Description: 


This function issues a command to rewind an audio playback the indicated number of 
milliseconds. 


Prototype: 


void OEMSoundPlayer Rewind (uint32 dwTime, void * pUser) 





Parameters: 


dwTime Number of milliseconds to rewind. 
pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 
It must also call AEESoundPlayer PlayCB with AEE SOUNDPLAYER REWIND. 


See Also: 
OEMSoundPlayer FastForward() 
OEMSoundPlayer Pause() 
OEMSoundPlayer Resume() 
Return to the List of functions 
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Eri OEM SoundPlayer Interface 


OEMSoundPlayer Stop() 


Description: 
This function issues a command to stop an audio playback. 


Prototype: 


void OEMSoundPlayer Stop(void * pUser) 





Parameters: 


pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 
It must also call AEESoundPlayer PlayCB with AEE SOUNDPLAYER ABORTED. 


See Also: 
OEMSoundPlayer Play() 
Return to the List of functions 
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OEMSoundPlayer Tempo() 


Description: 
This function issues a command to adjust the audio playback tempo. 


Prototype: 


void OEMSoundPlayer Tempo (uint32 dwTempoFactor, void * pUser) 





Parameters: 


dwTempoFactor New tempo value. 
pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 
It must also call AEESoundPlayer PlayCB with AEE SOUNDPLAYER TEMPO. 


See Also: 
None 
Return to the List of functions 


691 


Eri OEM SoundPlayer Interface 


OEMSoundPlayer Tune() 


Description: 
This function issues a command to adjust the an audio playback tune. 


Prototype: 


void OEMSoundPlayer Tune (int32 dwTuneFactor, void * pUser) 





Parameters: 


dwTuneFactor New tune value. 
pUser Client data to be sent back with the callback function. 


Return Value: 
None 


Comments: 
None 


Side Effects: 


AEESoundPlayer StatusCB is called with the command status. It can be one of the 
following status codes: 


AEE SOUNDPLAYER SUCCESS 
AEE SOUNDPLAYER FAILURE 
It must also call AEESoundPlayer PlayCB with AEE SOUNDPLAYER TUNE. 


See Also: 
None 
Return to the List of functions 
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OEM String Interface 


This section describes the String Interface functions that the AEE uses to perform formatting 
and printing operations on strings. 


List of functions 


Functions in this interface include: 


OEM FloatToWStr() 
OEM GetCHType() 
OEM UTF8ToWStr() 
OEM vxprintf() 

OEM WStrLower() 
OEM WsStrToFloat() 
OEM WsStrToUTF8() 
OEM WsStrUpper() 


The remainder of this section provides details for each function. 
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Eri OEM String Interface 


OEM FloatToWStr() 


Description: 
This function converts a floating point to a string. 








Prototype: 

boolean OEM FloatToWStr (double v, AECHAR * psz, int nSize) 
Parameters: 

V Floating point value. 

psz Destination string. 


nSize Size of destination string. 


Return Value: 
TRUE, if successful. 
FALSE, if fails (if psz is NULL or nSize is zero or lesser). 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Eri OEM String Interface 


OEM GetCHType() 


Description: 
This function returns the type (such as numeric or alpha) of a wide character. 


Prototype: 


TChType OEM GetCHType (AECHAR ch) 








Parameters: 


ch Input character. 


Return Value: 
Type of character, if successful. 
SC UNKNOWN, if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM UTF8ToWStr() 


Description: 
This function converts a UTF8 string to a wide string. 


Prototype: 


boolean OEM UTF8ToWStr 
( 
const byte * pSrc, 
int nLen, 

AECHAR * pDst, 

int nSize 


) 








Parameters: 
pSrc Input string. 
nLen Length of input string. 
pDst Destination string. 


nSize Size in bytes of destination. 


Return Value: 
TRUE, if successful. 
FALSE, if fails (if pSrc or pDst is NULL; if nSize is zero or lesser). 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM vxprintf() 


Description: 


This function prints a formatted string to a buffer, or determines how much room to 
allocate for a formatted string. This size includes the NULL terminator. 


Prototype: 

int32 OEM vxprintf 
( 
void * buf, 
uint32 £, 
const char * format, 
VA LIST list 
) 





Parameters: 
buf Buffer to write to. Use NULL to find out the size required for the string. 
f Maximum size of the buffer (0x7FFFFFFF). Use O (zero) with NULL buf to 
determine the size required for the string. The rest are reserved for flags. 
format String containing formatting. 
list Optional list of arguments based on formatting. 


Return Value: 
Number of bytes stored in buf. 
Or, number of bytes required for the formatted string including the NULL terminator. 
-1, if fails. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM WStrLower() 


Description: 
This function converts all upper case characters in a wide string to lower case. 


Prototype: 


void OEM WStrLower (AECHAR * pszDest) 








Parameters: 


pszDest 'Source/destination string. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM WsStrToFloat() 


Description: 
This function converts a string to a floating point value. 


Prototype: 


double OEM WStrToFloat (const AECHAR *psz) 








Parameters: 


psz Input string. 


Return Value: 
Floating point, if successful. 
O (zero), if fails (if psz is NULL). 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM WStrToUTF3() 


Description: 
This function converts a wide string to UTF8. 


Prototype: 


boolean OEM WStrToUTF8 
( 
const AECHAR * pSrc, 
int nLen, 
byte * pDst, 
int nSize 


) 








Parameters: 
pSrc Input string. 
nLen Length of input string. 
pDst Destination string. 


nSize Size in bytes of destination. 


Return Value: 
TRUE, if successful. 
FALSE, if fails (pSrc or pDst is NULL; nSize is zero or lesser). 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Eri OEM String Interface 


OEM WStrUpper() 


Description: 
This function converts all lower case characters in a wide string to upper case. 


Prototype: 


void OEM WStrUpper (AECHAR * pszDest) 








Parameters: 


pszDest 'Source/destination string. 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM Text Interface 


This section describes the Text Interface input functions that the AEE uses. OEMs can modify 
the reference implementation to add more text input modes for foreign languges or other input 
methods. 


List of functions 


Functions in this interface include: 


OEM TextAddChar() 

OEM TextCreate() 

OEM TextDelete() 

OEM TextDraw() 

OEM TextEnumMode() 
OEM TextEnumModeslnit() 
OEM TextGet() 

OEM TextGetCurrentMode() 
OEM TextGetCursorPos() 
OEM TextGetMaxChars() 
OEM TextGetModeString() 
OEM TextGetProperties() 
OEM TextGetRect() 

OEM TextGetSel() 

OEM TextKeyPress() 
OEM TextQueryModes() 
OEM TextQuerySymbols() 
OEM TextSet() 

OEM TextSetCursorPos() 
OEM TextSetEdit() 

OEM TextSetMaxChars() 
OEM TextSetProperties() 
OEM TextSetRect() 

OEM TextSetSel() 

OEM TextUpdate() 


The remainder of this section provides details for each function. 
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Eri OEM Text Interface 


OEM TextAddChar() 


Description: 


This function adds or overwrites a character at the current cursor location in the 
specified text control. 


Prototype: 


void OEM TextAddChar 
( 








OEMCONTEXT hTextField, 
AECHAR ch, 
b 
) 











oolean bOverStrike 


Parameters: 
hTextField Handle for the text control object. 
ch Wide character to be added to the text control. 


bOverStrike Overwrites the text at the cursor location. 


Return Value: 
None 


Comments: 


Overstrike is meaningful only if there is an insertion point rather than a selection and 
the insertion point is not at the very end of the text. If hTextField is NULL, the function 
simply returns. 


See Also: 
None 
Return to the List of functions 
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Eri OEM Text Interface 


OEM TextCreate() 


Description: 


This function creates a dynamic text control object. It uses the given rectangle pRect 
to create the text control. The pIShell and pIDisplay pointers are saved in the newly 
created context to be used by the text control for notification, drawing, and so forth. 


Prototype: 


OEMCONTEXT OEM TextCreate 
( 
const IShell* pIShell, 
const IDisplay* pIDisplay, 
const AEERect * pRect 
) 
































Parameters: 
pIShell Pointer to the IShell interface object. 
plDisplay Pointer to the IDisplay interface object. 
pRect Pointer to the rectangle specifying the bounds and location of the text 


control to be created. 


Return Value: 


OEMCONTEXT that can be used as the handle to the newly created text control, if 
successful. 


NULL, if fails. 


Comments: 
If pIShell, pIDisplay, or pRect is NULL, the function fails. 


See Also: 
None 
Return to the List of functions 
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Era OEM Text Interface 


OEM TextDelete() 


Description: 


This function deletes a dynamic text control object. The text control must have been 
created successfully using OEM TextCreate(). This function also frees memory and 
any other resources associated with this text control. 


Prototype: 


void OEM TextDelete (OEMCONTEXT hTextField) 

















Parameters: 


hTextField Handle for the text control object to be deleted. 


Return Value: 
None 


Comments: 
If hTextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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Era OEM Text Interface 


OEM TextDraw() 


Description: 


This function draws the text associated with a given text control object on the screen. 
Italso draws the associated items (such as Scroll Bar, Border, and Cursor) ifnecessary 
and if they are supported. 


Prototype: 


void OEM TextDraw (OEMCONTEXT NTextField) 

















Parameters: 


hTextField Handle for the text control object. 


Return Value: 
None 


Comments: 


When the TP PASSWORD property is set, please display a text buffer of **** in place 
of actual characters. You must maintain your original buffer of actual text. 


When in multitap mode, please allow the selection to appear while the user presses 
the key. After the selection is committed to text, show only the * character. 


If hTextField is NULL, the function perform no task and returns no errors. 


See Also: 
None 
Return to the List of functions 
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Eri OEM Text Interface 


OEM TextEnumMode() 


Description: 
This function gets the next text enumeration mode. 


Prototype: 


boolean OEM TextEnumMode (AEETextMode * pMode) 























Parameters: 
pMode [OUT] Pointer to the next text mode. 


Return Value: 
TRUE, if the next mode is valid. 
FALSE, if already at the end of the list. 


Comments: 
If pMode is NULL, the function returns FALSE. 


See Also: 
None 
Return to the List of functions 
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Eri OEM Text Interface 


OEM TextEnumModesilnit() 


Description: 


This function initializes the enumeration mode. It does not have an associated handle 
for the text control object. 


Prototype: 


void OEM TextEnumModesInit (void) 








Parameters: 
None 


Return Value: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Eres OEM Text Interface 


OEM TextGet() 


Description: 


This function gets the text associated with a given text control object, and returns a 
pointer to the text. 


Prototype: 


AECHAR* OEM TextGet (OEMCONTEXT hTextField) 




















Parameters: 


hTextField Handle for the text control object. 


Return Value: 
Pointer to the text string in the text control, if successful. 
NULL, if fails. 


Comments: 
If hTextField is NULL, the function returns NULL. 


See Also: 
None 
Return to the List of functions 
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Eres OEM Text Interface 


OEM TextGetCurrentMode() 


Description: 
This function returns the current text mode of the text control specified by hTextField. 


Prototype: 


AEEText InputMode OEM TextGetCurrentMode (OEMCONTEXT hTextField) 





























Parameters: 


hTextField Handle for the text control object. 


Return Value: 
Current text mode for the text control specified. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Era OEM Text Interface 


OEM TextGetCursorPos() 


Description: 
This function gets the absolute position of the cursor. 


Prototype: 


int32 OEM TextGetCursorPos (OEMCONTEXT hTextField) 

















Parameters: 


hTextField Handle for the text control object. 


Return Value: 


The O based position of the cursor. For example, if you have the Text Hi and the cursor 
is given as |: 


* |Hi would return O. 
* Hji would return 1. 
* Hil would return 2. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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Eri OEM Text Interface 


OEM TextGetMaxChars() 


Description: 


This function gets the maximum number of characters that can be added to the 
specified text control. 


Prototype: 


uint16 OEM TextGetMaxChars (OEMCONTEXT hTextField) 

















Parameters: 


hTextField Handle for the text control object. 


Return Value: 
Maximum number of characters for the text control specified by hTextField. 


Comments: 
If hTextField is NULL, the function returns O (zero). 


See Also: 
None 
Return to the List of functions 
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Eri OEM Text Interface 


OEM TextGetModesString() 


Description: 
This function returns the wide string corresponding to the current mode of the text 
control specified by hTextField. The mode strings are Multitap, Numbers, and 
Symbols. 


Prototype: 


void OEM TextGetModeString 
( 








OEMCONTEXT hTextField, 
AECHAR* szBuf, 
u 
) 











int1l6 len 


Parameters: 
hTextField [IN] Handle for the text control object. 
szBuf [IN] String corresponding to the mode of the text control. 
len [OUT] Length of the mode string buffer. 


Return Value: 
None 


Comments: 
If hTextField or szBuf is NULL, or if len is one or less, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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= OEM Text Interface 


OEM TextGetProperties() 


Description: 


This function returns the properties of the text control, such as frame type, multiline, or 
rapid entry (like T9). 


Prototype: 


uint32 OEM TextGetProperties (OEMCONTEXT hTextField) 

















Parameters: 


hTextField Handle for the text control object. 


Return Value: 
Property of the text control. 


Comments: 
Important properties are: 
TP MULTILINE, if setthe text control object is multiple line control. 
TP FRAME, if set, the text control object has a frame. 
TP RAPID MODE, if set, the text control object is in rapid mode. 


TP PASSWORD, if set, the text control displays * characters in place of real 
characters. 


Itis safe to ignore the following: 
TP NODRAW, if set, the text control object does not draw itself 


TP NOUPDATE, if set, the text control object does not call DISPLAY Update 
when it is not needed 


When using TP PASSWORD in multitap mode, please allow the selection to appear 
while the user presses the key. After the selection is committed to text, show only the 
* character. 


If hTextField is NULL, the function returns O (zero). 


See Also: 
None 
Return to the List of functions 
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Era OEM Text Interface 


OEM TextGetRect() 


Description: 
This function returns the rectangle corresponding to the bounds of this text control. 


Prototype: 


void OEM TextGetRect (OEMCONTEXT hTextField, AEERect *pOutRect) 





























Parameters: 


hTextField Handle for the text control object. 
pOutRect Rectangle corresponding to the bounds of the text control. 


Return Value: 
None 


Comments: 
If hTextField or pOutRect is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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Eri OEM Text Interface 


OEM TextGetSel() 


Description: 
This function gets the start and end locations for the selected text. 


Prototype: 


void OEM TextGetSel 
( 














OEMCONTEXT hTextField, 
int * pisSelStart, 

int * piSelEnd 

) 

















Parameters: 


hTextField [IN] Handle for the text control object. 
pSelStart [OUT] Start location of the text selection. 
pSelEnd [OUT] Ending location of the text selection. 


Return Value: 
None 


Comments: 
If htextField is NULL and piSelStart is non-NULL, the first entry is set to O (zero). 
If htextField is NULL and piSelEnd is non-NULL, the first entry is set to O (zero). 


See Also: 
None 
Return to the List of functions 


716 


Eri OEM Text Interface 


OEM TextKeyPress() 


Description: 


This function handles the key press events in a text control. When a key is pressed 
while a text control is active, this function is invoked, passing information relating to the 
key that has been pressed. The OEM layer must handle the key event and process it 
appropriately. 


Prototype: 


boolean OEM TextkKeyPress 
( 

OEMCONTEXT hTextField, 

AEEEvent eCode, 

uint32 dwKeyCode, 

uint32 dwkKeySyms 

) 
































Parameters: 
hTextField Handle for the text control object 
eCode Event code for the key event 


dwkKeyCode Key code of the key that has been pressed 
dwkKeySyms Not used. 


Return Value: 
The current text mode for the specified text control. 


Comments: 
None 


See Also: 
None 
Return to the List of functions 
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OEM TextQueryModes() 


Description: 


This function is invoked by the AEE to query the different text modes (such as T9 and 
MULTITAP) supported by the OEM layer. The AEE uses this information for two 
purposes: 


* To populate the pop-up menu containing selections for the different modes 
supported. 


* To notify the text control, using OEM TextSetEdit(), of the mode selected by the 
user. 


The OEM layer must populate the given data structure and return from this function. 


Prototype: 


int OEM TextQueryModes (AEETextMode ** ppTextMode) 

















Parameters: 


ppTextMode On return, this contains a valid pointer to an array of AEE TextMode 
containing information about the different modes supported by the 
OEM layer. The OEM layer must use the standard identifier 
OEM TEXT MODE SYMBOLS for symbols mode. Memory for this 
pointer must be allocated by the OEM. 


Return Value: 
Number of text modes supported by the OEM. 


Comments: 
The following is a brief description of how text modes are supported. 


* The AEE platform invokes the OEM function OEM TextQueryModes() to get 
information on the different text modes supported by the OEM. 

* The information obtained above is used to populate the menu containing 
selection strings for the different modes. 


* When the user selects a particular mode, the function OEM TextSetEdit() is 
invoked and is passed the ID of the mode that has been selected. lfthe user has 
not changed the mode, the ID is setto OEM TEXT MODE DEFAULT, informing 
the OEM layer to use the currently selected mode. 


* The OEM layer must use the standard ID OEM TEXT MODE SYMBOLS for 
supporting the symbol mode. All other IDs must be based out of 
OEM TEXT MODE USER. 


See Also: 
None 
Return to the List of functions 
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OEM TextQuerySymbols() 


Description: 


This function gets the buffer pszOut with the symbols. The length of the buffer is 
specified by size. 


Prototype: 


uint16 OEM TextQuerySymbols (AECHAR * pszOut, uint1l6 size) 








Parameters: 


pszOut Symbols buffer. 
size Size of the buffer. 


Return Value: 
Number of symbols put in the query buffer. 


If pszOut is NULL or if size is less than the number of OEM symbols, this function 
returns O (zero). 


Comments: 
If pszOut is NULL, the function returns O (zero). 


See Also: 
None 
Return to the List of functions 
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Bravo OEM Text Interface 


OEM TextSet() 


Description: 


This function sets the text of a given text control object. The text control must have 
been created successfully using OEM TextCreate(). Once the text has been set, 
OEM TextDraw() must be called to update the screen with the new text. 


Prototype: 


boolean OEM TextSet 

( 
OEMCONTEXT hNTextField, 
const AECHAR *pszText, 
int nChars) 























Parameters: 
hTextField Handle for the text control object. 
pszText Text string to be set into the text control. 
nChars Number of characters to set. 


Return Value: 
None 


Comments: 
If htextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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OEM TextSetCursorPos() 


Description: 
This function gets the absolute position of the cursor. 


Prototype: 


int32 OEM TextSetCursorPos (OEMCONTEXT hTextField, int32 nOffset) 

















Parameters: 


hTextField Handle for the text control object. 
nOfíset Absolute offset where the cursor is to be moved. 


Return Value: 
None 


Comments: 
This function should move the cursor to the O-based position of the cursor. 
If nOffset is > the length of the text, the cursor should be placed after the text. 
If nOffset is <= O, the cursor should be placed at the beginning of the text. 
For example, if you have the Text Hi and | represents the cursor: 


nOfíset=0 ]|Hi 
nOffset = -1 ]|Hi 
nOfíset=1 Hi 
nOfíset=2 Hi 


nOfíset = 100 Hil 


See Also: 
None 
Return to the List of functions 
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OEM TextSetEdit() 


Description: 
This function informs the text control whenever it goes in or out of focus. Typically, 
when the text control is in focus, the border and cursor are activated; when the text 
control goes out of focus, these items are de-activated. This function also informs the 
text control of the current text mode. 


Prototype: 


vvoid OEM TextSetEdit 





O 
( 
OEMCONTEXT hTextField, 
boolean bIsEditable, 
A 
) 




















EEText InputMode wmode 





Parameters: 


hTextField Handle for the text control object. 
blsEditable Flag to indicate if the text control object is in focus (that is, itis 
editable). 


wmode Text input mode. 


Return Value: 
None 


Comments: 
If htextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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OEM TextSetMaxChars() 


Description: 


This function sets the maximum number of characters that can be added to the 
specified text control. 














Prototype: 

void OEM TextSetMaxChars (OEMCONTEXT hTextField, uint1l6 wMaxChars) 
Parameters: 

hTextField Handle for the text control object. 


wMaxChars New maximum number of characters in this text control. 


Return Value: 
None 


Comments: 
If htextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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OEM TextSetProperties() 


Description: 


This function sets the properties of the text control, such as frame type, multiline, rapid 
entry (such as T9), or a combination of properties. 

















Prototype: 

void OEM TextSetProperties (OEMCONTEXT hTextField, uint32 dwProperties) 
Parameters: 

hTextField Handle for the text control object. 


dwProperties Properties (TP FRAME, TP MULTILINE, TP RAPID MODE, ora 
combination). 


Return Value: 
None 


Comments: 
Important properties are: 
TP MULTILINE, if set, text control object is multiple line control 
TP FRAME, if set, text control object has a frame 
TP RAPID MODE, if set, text control object is in rapid mode 


TP PASSWORD, if set, text control displays * characters in place of real 
characters 


Itis safe to ignore the following properties: 
TP NODRAW, if set, text control object does not draw itself 


TP NOUPDATE, if set, text control object does not call IDIPLAY Update when not 
needed 


When using TP PASSWORD in multitap mode, please allow the selection to appear 
while the user presses the key. After the selection is committed to text, show only the 
* character. 


If htextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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OEM TextSetRect() 


Description: 
This function returns the rectangle corresponding to the bounds of this text control. 


Prototype: 


void OEM TextSetRect (OEMCONTEXT hTextField, const AEERect *pInRect) 





























Parameters: 


hTextField Handle for the text control object. 
pInRect New bounds for the text control. 


Return Value: 
None 


Comments: 
If htextField or pInRect is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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OEM TextSetSel() 


Description: 
This function sets the start and end locations for the text selection. 




















Prototype: 

void OEM TextSetSel (OEMCONTEXT hTextField, int iSelStart, int iSelEnd) 
Parameters: 

hTextField Handle for the text control object. 

iSelStart Start location of the text selection. 

iSelEnd Ending location of the text selection. 


Return Value: 
None 


Comments: 
If htextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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OEM TextUpdate() 


Description: 


This function draws the text associated with a given text control object on the screen if 
the text control is modified. 


Prototype: 


void OEM TextUpdate (OEMCONTEXT hTextField) 

















Parameters: 


hTextField Handle for the text control object. 


Return Value: 
None 


Comments: 
If htextField is NULL, the function simply returns. 


See Also: 
None 
Return to the List of functions 
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Data Types 


This section describes the data types used by the BREW OEM API functions. These data 
types define the format and content of the data that is passed by applications to the BREW 
functions and received by the applications. Type definitions for the BREW data structures are 
contained in the BREW header files. Some data structures are specific to a particular BREW 
interface and are contained in the header files for those interfaces. Other data structures are 
used by more than one interface and are found in the files AEE.h and AEEError.h. The 
description of each BREW function contains links to the descriptions of all relevant data 
structures. 


BREW data structures are of three main types: 


* Structures and Unions: Some BREW functions take pointers to structures as input 
parameters. To use such a function, populate an instance of a structure and pass a 
pointer to the instance when calling the function. Other BREW functions return 
pointers to structures as output. This section describes each field in each of the 
BREW structures. 


* Enumerated Types: Some BREW variables and structure members take values 
from a finite set defined by the C typedef enum construct. For example, the font types 
supported by text-drawing functions are specified with an enumerated-type 
definition. This section describes each value of each enumerated type. 


* Constant Definitions: The BREW functions use constants that are defined with the 
tdefine construct. One common use of constants is to define a set of bit masks for 
testing and setting the values of the bits in a bit vector variable. Each control defines 
a set of bit mask constants that are used to test and set the values of each of the 
control's properties. This section describes each set of related constants. 
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List of data structures 


Data structures in this interface include: 


AEE Events 

AEE ITextCtl Properties 
AEE Static Properties 
AEE ADDR RECID NULL 
AEE3DColor 
AEE3DCoordinateTransformType 
AEE3DCullingType 
AEE3DEventNotify 
AEE3DLight 
AEE3DLightingMode 
AEESDLightType 
AEESDMaterial 
AEE3SDMatrixMode 
AEE3DModelData 
AEE3DModelPoly 
AEE3DModelSegment 
AEE3DPoint 
AEE3DPoint16 
AEE3DPrimitiveType 
AEE3SDRenderType 
AEES3DRotateType 
AEES3DTexture 
AEE3DTextureSamplingType 
AEESDTextureType 
AEESDTextureWrapType 
AEESDTLVertex 
AEE3DTransformMatrix 
AEES3DVertex 

AEE DBError 

AEE DBReclnfo 
AEEAppStart 
AEEBitmaplInfo 
AEECallHistoryEntry 
AEECallHistoryField 
AEECameraNotify 
AEEDevicelnfo 
AEEDeviceltem 
AEEDNSClass 
AEEDNSItem 
AEEDNSType 
AEEFilelnfoEx 
AEEFileUselnfo 
AEEFontinfo 
AEEGPSCornfig 
AEEGPSInfo 
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AEEParminto 
AEEPosAccuracy 


AEERasterOp 
AEERect 


AEERingerCat 

AEERingerCatiD 

RE ERingerEvent 
rID 
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CMediaQCP 
Configuation Parameters 
CtiAdditem 
CtlValChange 

FileAttrib 

FileInfo 
GSMSMSEncodingType 
GSMSMSMsg 
GSMSMSMsgType 
GSMSMSRawMsg 
GSMSMSStatusType 
GSMSMSStorageType 
I3D Events 

IDC COMMAND RESERVED 
IDIB 

INAddr 

INPort 

[Transform Properties 
NativeColor 

NetSocket 

NetState 
OEMAppEvent 
oemLogType 
PFNCBCANCEL 
PFNDLTEXT 
PFNMEDIANOTIFY 
Q12 Fixed Point Format 
Q14 Fixed Point Format 
Q16 Fixed Point Format 
Q3D File Format 
AEEObjectHandle 
PFNPOSITIONCB 
PFNRINGEREVENT 
PFNSIONOTIFY 
PhonesState 

RGBVAL 

TAPIStatus 

Tile Properties 

Tile Map Properties 


The remainder of this section provides details for each function. 
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AECHAR 


Description: 
AECHAR is BREW defined data type for wide strings. 


Definition: 
typedef uint16 AECHAR; 





Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEE Events 


Description: 


The defined AEE events that can be received by an applet or control. For each event, 
the wParam and dwParam parameters, if any, that are passed to the applet or control 
are given. 


Definition: 
The following tables list the event codes and key codes supported by BREW. 


Key Codes are received with EVT KEY, EVT KEY PRESS, EVT KEY RELEASE, and 
EVT KEY HELD events. 


Event codes 


Event code Description Parameters 





EVT ALARM Alarm event. wParam = Alarm Code, dwParam = 0. 
EVT APP BROWSE FILE Called after 

EVT APP START. 
EVT APP BROWSE URL Called after EVT APP START dwParam = (const AECHAR * pURL). 


EVT APP CONFIG Alternate application start. wParam = 0, dwParam = 0. 
Configuration screen shown. 
EVT APP HIDDEN - Alternate application start. wParam = 0, dwParam = 0. 
CONFIG Configuration screen hidden. 
EVT APP NO CLOSE Application should not be 
closed 


EVT APP NO SLEEP Application is working - called 
after long periods of non-idle 


application 

EVT APP RESUME Application resume. wParam = 0, dwParam = 0. 

EVT APP START Application start. wParam = 0, dwParam = const char 
*(arguments). 

EVT APP STOP Application stop. wParam = 0, dwParam = boolean *(flag 
to indicate if application wants to close 
now or later. Default is now. 

EVT APP SUSPEND Application suspend. wParam = 0, dwParam = 0. 
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Event code Description Parameters 
EVT BUSY Sentto application to wParam=0, dwParam=0. 

determine if the application 
can be suspended or stopped. 
Application must return TRUE 
if it does not want to be 
suspended or stopped. 
Typically, applications return 
FALSE. 

EVT CB COPY Copy request - dwParam = (const char *) 
const char * indicating the preferred 
format, 

NULL for copy all 
EVT CB CUT Cut request - dwParam = (const char *) 


EVT CB PASTE 
EVT CHAR 


EVT COMMAND 


EVT COPYRIGHT END 


EVT CTL ADD ITEM 
EVT CTL CHANGING 


EVT CTL MENU OPEN 
EVT CTL SEL CHANGE 
D 

EVT CTL SET TEXT 
EVT CTL SET TITLE 
EVT CTL SKMENU PAG 
E FULL 

EVT CTL TAB 


EVT CTL TEXT MODE 
CHANGED 


Paste request - 


Character event. 


Application custom controls 
event. 


Dialog event: Copyright dialog 
ended. 


Message interface to add item. 


Change control event. 


Sent by ITextCtl before menu 
is activated. 


Sent by IMenuCtl when 
selection has changed 


Set text control event. 

Set control title event. 
Sent by IMenuCtl when SK 
menu page is full 


Application tab event. 


Sent by ITextCtl when input 
mode was changed 
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const char * indicating the preferred 
format, 


NULL for cut all 
no parameters 


wParam = AECHAR code of character, 
dwParam = bitflags for modifier keys. 


wParam = user command ID, dwParam 
= user data. 


wParam = DialoglD, dwParam = IDialog 


wParam = 0, dwParam = CtlAddltem *. 


wParam = 0, dwParam = 
CtlValChange*. 


wParam = 0, dwParam = 
IMenuCtl *. 


wParam - selection ID, dwParam == 
IMenuCtl * 


wParam = ID, dwParam = if ID is not 
zero, then resource file, else text. 


wParam = ID, dwParam = if ID is not 
zero, then resource file, else text. 


dwParam == IMenuCtl * 


wParam = 0-left, 1-right, dwParam = 
pointer to the control. 
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Event code Description Parameters 
EVT DIALOG END Dialog event: Dialog wParam = DialoglD, dwParam = TDialog 
completed normally. * The dwPram has 1 for a "Yes" 
response and 2 for "No" response from 
user. 
EVT DIALOG INIT Dialog Event: Controls wParam = Dialog ID, dwParam = 


EVT DIALOG START 


EVT FLIP 


EVT KEY 


EVT KEY HELD 


EVT KEY PRESS 


EVT KEY RELEASE 


EVT KEYGUARD 


EVT LOCKED 


EVT MOD LIST CHANG 


ED 


EVT NOTIFY 


EVT UPDATECHAR 


EVT USER 


created, pre-init values, flags, IDialog *. 
and other items. 


Dialog event: Dialog opening. wParam = DialoglD, dwParam = IDialog 


Device-specific event: Sent to wParam = TRUE if open, FALSE if 


application when flip-type closed; dwParam = 0. 

(clam-shell) device is opened 

or closed. 

Key handling event. wParam = key code (see Key codes 
table), dwParam = bitflags for modifier 
keys. 

Key held event. The hold time wParam = key code (see Key codes 

is device-specific. Not table), dwParam = bitflags for modifier 

supported in Emulator. keys. 

Keypress event. wParam = key code (see Key codes 
table), dwParam = bitflags for modifier 
keys. 

Key release event. wParam = key code (see Key codes 
table), dwParam = bitflags for modifier 
keys. 


Device-specific event: Sent to wParam = TRUE if keyguard is on, 
application when device FALSE otherwise; dwParam = 0. 
keypad is locked. 


Device-specific event: Sent to wParam = TRUE if locked, FALSE 
application when device user otherwise; dwParam = 0. 
interface is locked. 


List of modules changed. May 
be sent while application 
suspended! 


BREW-generated notification  wParam = 0, dwParam = AEENotify *. 
or application-registered 
notification event. 


Character update event. wParam = AECHAR code of character, 
dwParam = bitflags for modifier keys. 


Start of application/user- Private to application. 
defined events. 
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Members: 


None 


Comments 
The user-defined events start from EVT USER. 


See Also: 
None 
Return to the List of data structures 
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AEE ITextCtl Properties 


Description: 
The properties defined for ITextCtl Interface. 


Definition: 
TP MULTILINE If set, text control object is multiple line control. 
TP FRAME If set, text control object has a frame. 
TP T9 MODE (Deprecated) 
TP RAPID MODE Supports Rapid Entry and uses as default 
TP NODRAW Disables all drawing by the control 
TP NOUPDATE Disables wasteful IDISPLAY Update calls 
TP PASSWORD Displays ***, manages correct buffer chars 


TP INTEGRALHEIGHT If set this forces the rectangle of the TextCtl to be of an even 
height with respect to the character height. Basically there 
will be no left over space and the text will fit naturally into the 
text control. Rather than showing 1.5 lines of text it will show 
either 1 or 2. It will round to the nearest line height and snap 
to it. 

TP FIXSETRECT Actual height more closely represents requested height. 


Members: 
None 


Comments 
None 


See Also: 
ITEXTCTL SetProperties() 
ITEXTCTL GetProperties() 
Return to the List of data structures 
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AEE Static Properties 


Description: 


The properties defined for IStatic Interface. 


Definition: 
ST CENTERTEXT 
ST CENTERTITLE 
ST NOSCROLL 
ST TEXTALLOC 
ST TITLEALLOC 
ST MIDDLETEXT 
ST UNDERLINE 
ST ICONTEXT 
ST ASCII 
ST ENABLETAB 
ST ENABLE HLGHT 


Members: 
None 


Comments 
None 


See Also: 


Center Text 

Center Title 

Do not scroll text 

Text allocated on heap - dialog takes responsibility of freeing it. 
Title allocated on heap - dialog takes responsibility of freeing it. 
Text is drawn in the middle of the screen 

Underline the title 

Text is IImage * 

Text is single-byte 

Generate EVT CTL TAB when at top or bottom 

Highlights the static, if it has focus 


ISTATIC SetProperties() 
ISTATIC GetProperties() 
Return to the List of data structures 
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AEE ADDR RECID NULL 


Description: 
This constant defines a NULL record ID in the BREW Address Book interface. 


Definition: 
ftdefine AEE ADDR RECID NULL Oxffff 

















Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEE3DColor 


Description: 
This STRUCT defines the color format used in I3D API. 


Definition: 
typedef struct ( 
uint8 r,g,b,a; 
+ AEE3DColor; 














Members: 
r: RED value. 
g: GREEN value. 
b: BLUE value. 
a: ALPHA value. 


Comments: 


Alpha blending is not supported in this release. The default color scheme is 5-6-5 for 
(r, g,b). 


See Also: 
None 
Return to the List of data structures 
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AEE3DCoordinateTransformType 


Description: 
NOTE: This data item is currently not supported. 
This ENUM defines the coordinate transformation type. 


Definition: 
typedef enum 








f 

AEE3D COORDINATE TRANSFORM NONE =0, 
AEE3D COORDINATE TRANSFORM SCREENMAP, 
A 

A 

) 




















EE3D COORDINATE TRANSFORM PROJECTION, 
EE3D COORDINATE TRANSFORM MODELVIEW 
























































AEE3DCoordinateTransformType; 





Members: 


AEESD CORDINATE TRANSFORM NONE: Vertices are given in screen 
coordinates. No transformation is necessary. 


AEESD CORDINATE TRANSFORM SCREENMAP: Screen mapping is made. 


AEESD CORDINATE TRANSFORM PROJECTION: Screen mapping is made after 
projection. 


AEESD CORDINATE TRANSFORM MODELVIEW: Vertices go through the entire 
transformation pipeline: model-view, projection, and screen mapping. 


Comments: 
None 


See Also: 
I3D GetCoordTransformMode() 
I3D SetCoordTransformMode() 
Return to the List of data structures 
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AEE3DCullingType 


Description: 
This ENUM defines which triangles should be discarded before they are rendered. By 
default, triangles with vertices arranged in counterclockwise rotation will be visible. A 
counterclockwise rotation indicates front-facing. A clockwise rotation is considered 
back facing. 


Definition: 
typedef enum 
f 





AEE3D CULLING BACK FACING = -1, 
AEE3D CULLING FRONT FACING = 1 
+ AEE3DCullingType; 



































Members: 


AEESD CULLING BACK FACING: All triangles with vertices arranged in clockwise 
rotation will be visible. And triangles that are back facing will be discarded when they 
are drawn. 


AEESD CULLING FRONT FACING: All triangles with vertices arranged in counter- 
clockwise rotation will be visible. And triangles that are front facing will be discarded 
when they are drawn. 


Comments: 
None 


See Also: 
I3D SetCullingMode() 
I3D GetCullingMode() 
Return to the List of data structures 
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AEESDEventNotify 


Description: 


Data Types 


This STRUCT defines a 3D event notifier. 


Definition: 


typedef struct . 


f 
I3D* 
int16 
int16 
void* 





























EventNotify 


p3D; 
nEventType; 
nErrorCode; 
pData; 





+) ABEE3DEventNotify; 





Members: 


psD Pointer to I3D instance associated with the event. 

InEventType Type of event that occurred. 

InErrorCode The error code. 

pData Pointer to event data. Could be dropped frame, status, and so on. 


Comments: 


Your registered event notifier will be passed this event notify type. 


See Also: 


I3D RegisterEventNotify() 


I3D StartFrame() 


Return to the List of data structures 
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AEESDLight 


Description: 
This STRUCT defines a 3D light type. 


Definition: 

typedef struct  AEE3DLight ( 
AEE3DLightType type; 
AEE3DColor color; 
AEE3DPoint direction; 
| AEE3DLight; 


















































Members: 
type: The type of light to use. 
color: The color of the light. 
direction: The direction of the light. 


Comments: 
None 


See Also: 
I3D SetLight() 
I3D SetLightingMode() 
AEES3DLightType 
Return to the List of data structures 
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AEE3DLightingMode 


Description: 
This ENUM defines constants that determine which lighting mode to use. 


Definition: 
typedef enum 











EE3D LIGHT MODE DIFFUSED = 0, 


EE3D LIGHT MODE COLOR DIFFUSED, 
EE3D LIGHT MODE DIFFUSED COLOR SPECULAR, 

EE3D LIGHT MODE COLOR DIFFUSED COLOR SPECULAR 
EE3D LIGHT MODE NONE 


AEE3DLightingMode; 































































































-DPpoPpppD- 


Members: 
AEE3D LIGHT MODE DIFFUSED: lighting will be white diffused only. 
AEE3D LIGHT MODE COLOR DIFFUSED: lighting will be color diffused. 


AEESD LIGHT MODE DIFFUSED COLOR SPECULAR: lighting will be white 
diffused with color specular light. Both lights are in the same direction. 


AEESD LIGHT MODE COLOR DIFFUSED COLOR SPECULAR: lighting will be 
color diffused with color specular light. Each light can have a different direction. 


Comments: 
AEE3D LIGHT MODE DIFFUSED COLOR SPECULAR is the default. 


AEE3D LIGHT MODE COLOR DIFFUSED COLOR SPECULAR is the most CPU 
intensive. 


See Also: 
I3D SetLight() 
I3D SetLightingMode() 
Return to the List of data structures 
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AEES3DLightType 


Description: 
This ENUM defines which will determine what light to use. 


Definition: 
typedef enum 
f 
AEE3D LIGHT DIFFUSED = 0, 
AEE3D LIGHT SPECULAR 












































JAEE3DLight Type; 





Members: 
AEESD LIGHT DIFFUSED: define diffused light. 
AEESD LIGHT SPECULAR: define specular light. 


Comments: 
None 


See Also: 
I3D SetLight() 
I3D SetLightingMode() 
Return to the List of data structures 
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AEE3DMaterial 


Description: 
This. 


Definition: 


typedef struct  AEE3DMaterial ( 
AEE3DColor color; 

uint8 shininess; 

uint8 emissive; 

) AEE3DMaterial; 



































Members: 
color: The color of the material 
shininess: The shininess value (0-255) 
emissive: The emissive value (0-255) 


Comments: 
None 


See Also: 
I3D SetMaterial() 
Return to the List of data structures 
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AEE3DMatrixMode 


Description: 


This ENUM defines constants that determine which matrix to use when pushing or 
popping a matrix. You should set this mode before calling push and pop matrix. 


Definition: 
typedef enum 
f 
AEE3D MATRIX MODE MODELVIEW = 0 
) AEE3DMatrixMode; 









































Members: 


AEESD MATRIX MODE MODELVIEW: Use the model view matrix when pushing 
and popping a matrix. 


Comments: 
None 


See Also: 
I3D PushMatrix() 
AEE3SDMatrixMode() 
Return to the List of data structures 
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AEE3DModelData 


Description: 


Data Types 


This STRUCT defines a 3D model that will be used by the |3DModel functions. 


Definition: 





typedef struct | AEE3DModelData 











f 
uint8 
uint8 
uint8 
uint8 
uint16 
uint16 
uint16 


uint1l6 extra; 









































oid* pReserved; 





PS PPrpprPpprprps 











EE3DPoint* pOrignalVertex tbl1; 
EE3DVertex* pVertex tb1; 
EE3DModelPoly* pPoly tb1; 
EE3DColor* pMaterialColor tbl1; 


model index; 
num material; 
num texture; 
num segment; 
num vertex; 
reserved; 

num poly; 














EE3DModelSegment* pSegment tb1; 
EE3DTransformMatrix* pModelViewMatrixStack; 


EE3DTexture** pTexture tbl; 


void* extra features; 
unsigned char* pAlloc mem; 








;+ AEE3DModelData; 











Members: 


model index 

num material 

num texture 

num segment 
num vertex 
reserved 

num poly 

extra 
pOrignalVertex tbl 
pVertex tbl 

pPoly tbl 
pMaterialColor tbl 
pSegment tbl 
pModelViewMatrixStack 


pReserved 


The model index value 

Number of materials 

Number of textures 

Number of segments 

Number of vertices 

reserved field 

Number of polygons 

For future use 

Pointer to original vertex table (list of vertices) 
Pointer to vertex table (list of vertices) 

Pointer to polygon table (list of polygons) 

Pointer to material color table (list of material colors) 
Pointer to segment table (list of segments) 

Pointer to a list of Model View transformation matrices. 


Index range (0,num segment-1) contains the segment's 
transformation matrices. 


for internal use only. 
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pTexture tbl Pointer to an array of texture bitmaps in IDIB format 
extra features currently not used. 
pAlloc mem Pointer to allocated memory pool for Model, Data block 
transfer are faster if data is continuous for firmware 
acceleration. 
Comments: 
The struct is designed to hold a 3D model in the Q3D format. 
See Also: 
Q3D File Format 
AEE3DModelSegment 
AEE3DModelPoly 


Return to the List of data structures 
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AEE3DModelPoly 


Description: 
This STRUCT defines a polygon (triangle) that will be used by the |3DModel functions. 


Definition: 
typedef struct | AEE3DModelPoly ( 

uint1l6 vio0O; 
uintl6 vil; 
uintl6 viZ2; 
uintl6 attr; 

intl6 pnorm x; 

intl6 pnorm y; 

intl6 pnorm z; 

+) AEE3DModelPoly; 


























Members: 

viO: vertex index O 

vif: vertex index 1 

vi2: vertex index 2 

attr: polygon attribute vector which indicates: 
bits 0-7: color index 
bits 8-10: texture index. This is the index value into the pTexture tbl. The 
Texture tbl is defined in AEE3DModelData structure. 


bits 11-12: texture method (00: not textured, 01: replace, 10: mixed, 11: 
blending) 


bits 13: flag for shading (O: no shading) 

bits 14: flag for double draw (0: no double draw) 

bits 15: flag for using polygon level feature (0: use segmental features) 
pnorm x: 
pnorm y: 
pnorm z: The polygon normal 


Comments: 
None 


See Also: 
AEE3DModelSegment 
Return to the List of data structures 


noi 


Brevi Data Types 


AEE3DModelSegment 


Description: 
This STRUCT defines a segment that will be used by the |3DModel functions. 


Definition: 
typedef struct | AEE3DModelSegment ( 
uint16 num vertex; 
uint16 vertex offset; 
uint1l6 reserved; 














uint16 num face; 
uint16 face offset; 
uint1l6 attr; 

uint16 material attr; 
+ AEE3DModelSegment ; 














Members: 
num vertex: number of vertices in the segment 
vertex offset: offset of vertex in the vertex buffer. 
reserved: reserved for future use. 
num face: number of polygons. 


face offset: offset in the pPoly tbl defined in AEE3SDModelData. This offset will be 
where the first polygon starts in the Poly tbl for this segment. 


attr: segment level attributes. 
material attr: material attributes. 


The attribute values here have the same definition as that in AEE3DModelPoly. It 
indicates: 


bits 0-7: color index. 


bits 8-10: texture index This is the index value into the pTexture tbl. The 
Texture tbl is defined in AEE3DModel structure. 


bits 11-12: texture method (00: not textured, 01: replace, 10: mixed, 11: blending). 
bits 13: flag for shading (0: no shading). 
bits 14: flag for double draw (0: no double draw). 
bits 15: flag for using polygon level feature (0: use segmental features). 
The Material attributes values are as follows: 
bits 0-7: shininess (0-255). 
bits 8-15: emissive (0-255). 


Comments: 
None 


See Also: 
AEE3DModelPoly 
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Return to the List of data structures 
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AEE3DPoint 


Description: 
This STRUCT defines a 3D point type. 


























Definition: 
typedef struct  AEE3DPoint ( 
int32 x; 
int32 y; 
intõ2: 2; 
) AEE3DPoint; 
Members: 


x: X coordinate. 
y: Y coordinate. 
z: Z coordinate. 


Comments: 
The coordinates are in Q16 format. 


See Also: 
None 
Return to the List of data structures 
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AEE3DPoint16 


Description: 
This STRUCT defines a 3D 16-bit point type. 


























Definition: 
typedef struct  AEE3DPoint16 ( 
intl6 x; 
intl6 y; 
intl6 z; 
) AEE3DPoint 16; 
Members: 


x: X coordinate. 
y: Y coordinate. 
z: Z coordinate. 


Comments: 
The coordinates are in Q16 format. 


See Also: 
None 
Return to the List of data structures 
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AEE3DPrimitiveType 






























































Description: 
This ENUM defines constants that determine the primitive type to use with vertex 
arrays. 
Definition: 
typedef enum 
t 
AFE3D TRIANGLE, 
AEE3D TRIANGLE FAN, 
AFE3D TRIANGLE STRIP, 
+) AEE3DPrimitiveType; 
Members: 
AEESD TRIANGLE Vertices in the array form triangles. 


AEESD TRIANGLE FAN Vertices in the array form a triangle fan. 
AEESD TRIANGLE STRIP | Vertices in the array form a triangle strip. 


Comments: 
None 


See Also: 
I3D CalcVertexArrayNormal() 
I3D CalcVertexArrayColor() 
Return to the List of data structures 
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AEE3DRenderType 


Description: 


Data Types 


This ENUM defines 3D rendering types. It determines how each triangle will be filled. 


























































































































Definition: 
typedef enum 

f 
AEE3D RENDER FLAT SHADING = 0, 
AEE3D RENDER FLAT TEXTURE FAST SHADING, 
AEE3D RENDER FLAT TEXTURE SHADING, 
AEE3D RENDER SMOOTH SHADING, 
AEE3D RENDER SMOOTH TEXTURE FAST SHADING, 
AEE3D RENDER SMOOTH TEXTURE SHADING, 
AEE3D RENDER TEXTURE REPLACE, 
JAEE3DRenderType; 

Members: 


AEESD RENDER FLAT SHADING: Each triangle is filled with the same color as the 
color of the first vertex. 








AEE3D RENDER FLAT TEXTURE 
averaged with surface colors. 
AEE3D RENDER FLAT TEXTURE 






































- FAST SHADING: Flat shading with texture colors 


- SHADING: Flat shading with texture colors blended 


with surface colors. (higher quality, slower performance) 


AEESD RENDER SMOOTH SHADING: Each triangle is filled with color interpolated 
across the three vertices. 








AEES3D RE 











AEESD RE 











;NDER. SMOOTH 
averaged with surface colors. 





EXTURI 


E FAST SHADING: Smooth shading with texture colors 








'NDER SMOOTH 














EXTURE | 





SHADING, : Smooth shading with texture colors 





blended with surface colors. (higher quality, slower performance) 
AEE3D RENDER TEXTURE REPLACE: Texture is as a decal. 


Comments: 


Render type significantly influences rendering performance. Flat shading is the fastest 
whereas smooth texture blending is the slowest. 


See Also: 


I3D GetRenderMode() 
I3D SetRenderMode() 
Return to the List of data structures 
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AEE3DRotate Type 


Description: 
This ENUM defines what axis to use when calculating a rotational matrix. 


Definition: 
typedef enum 
f 
AEE3D ROTATE X, 
AEE3D ROTATE Y, 
AEE3D ROTATE Z 
JAEE3DRotateType; 












































Members: 
AEESD ROTATE X: rotate about the X axis. 
AEESD ROTATE Y: rotate about the Y axis. 
AEESD ROTATE Z: rotate about the Z axis. 


Comments: 
None 


See Also: 
I3DUtil GetRotateMatrix() 
I3DUtil GetRotateVMatrix() 
Return to the List of data structures 


798 


brew. 


Data Types 


AEE3DTexture 


Description: 


This STRUCT defines the texture for a 3D Model. All texture images need to be 
converted into an IBitmap format. An application needs to decode and palettize (if 
necessary) these images and set the decoded raw pixel image (8-bits per pixel 
arranged row-by-row) to the pixel map component of IBitmap, and the palette to the 
palette. The width and height of the pixel map need to be a power of 2, and no greater 
than 256. Color depth of the palette ranges from 1-8. 


Definition: 
typedef struct  AEE3DTexture ( 


























AEE3DTextureType type; 











AEE3DTextureSamplingType SamplingMode; 





AEE3DTextureWrapType Wrap s; 

















AEE3DTextureWrapType Wrap t; 








uint32 BorderColorIndex; 


IBitmap *pImage; 


) AEE3DTexture; 
Members: 
Type The texture type 
SamplingMode Sampling type 
Wrap s Wrap mode in horizontal direction 
Wrap t Wrap mode in vertical direction 
BorderColorindex Index into the color palette for texture border color 
*plImage Pointer to IBitmap structure 
Comments: 
Image decoding should be done at program initialization. 
See Also: 


IBitmap Interface 
AEESDTextureSamplingType 
AEE3DTextureWrapType 
AEE3DColor 

Return to the List of data structures 
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AEE3D TextureSamplingType 


Description: 


This ENUM defines texture sampling types. Texture sampling refers to how to 
determine which texel (or texels) to use for a given fragment. 


Definition: 
typedef enum 
f 
AEE3D TEXTURE SAMPLING NEAREST = 0 
JAEE3DTextureSamplingType; 









































Members: 


AEESD TEXTURE SAMPLING NEAREST: Texture is sampled from the nearest 
neighbor. 


Comments: 
Other sampling methods may be supported in future releases. 


See Also: 
I3D GetTexture() 
I3D SetTexture() 
Return to the List of data structures 
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AEE3DTextureType 


Description: 
This ENUM defines texture types. 


Definition: 
typedef enum 
f 
AEE3D TEXTURE DIFFUSED, 
JAEE3DTextureType; 



































Members: 
AEE3D TEXTURE DIFFUSED: The diffused texture. 


Comments: 
Other texture types may be supported in future releases. 


See Also: 
I3D SetTexture() 
I3D GetTexture() 
Return to the List of data structures 
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AEE3DTextureWrapType 


Description: 


This ENUM defines the texture wrapping modes. The wrapping mode controls how a 
texel is selected when the texture coordinate goes beyond the size of the texture 
























































image. 
Definition: 

typedef enum 
( 
AEE3D TEXTURE WRAP REPEAT, 
AEE3D TEXTURE WRAP MIRROR, 
AEE3D TEXTURE WRAP CLAMP, 
AEE3D TEXTURE WRAP BORDER 
) 











AEE3DTextureWrapType; 





Members: 
AEESD TEXTURE WRAP REPEAT: Texture is repeated. 
AEESD TEXTURE WRAP MIRROR: Texture is mirrored and repeated. 
AEESD TEXTURE WRAP CLAMP: Border pixel is used. 


AEESD TEXTURE WRAP BORDER: Border color defined in texture structure is 
used. 


Comments: 
None 


See Also: 
I3D SetTexture() 
I3D GetTexture() 
Return to the List of data structures 
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AEESDTLVertex 


Description: 


This STRUCT defines the tlvertex used in the I3D API. It includes the location 
(x,y,Z,W), color(r,g,b,a), and texture coordinates(s.t). 























Definition: 
typedef struct  AEE3DTLVertex ( 
inta2 xi 
1nt32: vs 
int32 2; 
intl6 w; 
uint8 r; 
uint8 g; 
uint8 b; 
uint8 a; 
uint8 s; 
uint8 t; 
) AEE3DTLVertex; 
Members: 
X,Yy,Z,W Location (x,y,Z,w). 
rg,b,a Color of vertex. 
st One set of normalized (0-255) texture coordinates. 
Ss is the horizontal coordinate. 
tis the vertical coordinate. 
Comments: 
None. 
See Also: 


I3D CalcVertexArrayColor() 

I3D CalcVertexArrayNormal() 

I3D RenderTriangles() 

Return to the List of data structures 
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AEE3DTransformMatrix 


Description: 
This STRUCT defines the model view transformation matrix (3x4). 


The rotation part (left 3x3) is in Q12 fixed. The translation or shift part 


(right 3x1) should have the same Q factor as the vertex coordinate (Q16). 
| mOO mO01 mO2 moOS | 
|m10m1f m12m13] 
| m20 m21 m22 m28 | 


Definition: 
typedef struct | AEE3DTransformMatrix ( 


Members: 
mo00: 
mo01: 
moOZ: 
moO3: 
mio: 
m11: 
m1Z2: 
m13: 
m20: 
m21: 
m22: 
m23: 


in 


Pop Do 


õ 


Do o 


n 
n 





i 
i 
i 
i 
i 
E 
i 
i 
i 
i 
in 
) 




















t32 m0O0; 
t32 m01; 
t32 m02; 
t32 m03; 
t32 mlO0; 
t32 mll; 
t32 ml2; 
t32 m13; 
t32 m20; 
t32 m21; 
t32 m22; 
E32: ma3s 
AEE3DTransformMatrix; 














element at 1st row, 1st column, x-scaling. 
element at 1st row, 2nd column, xy-shearing. 
element at 1st row, 3rd column, xz-shearing. 
element at 1st row, 4th column, x-shift. 
element at 2nd row, 1st column, yx-shearing. 
element at 2nd row, 2nd column, y-scaling. 
element at 2nd row, 3rd column, yz-shearing. 
element at 2nd row, 4th column, y-shift. 
element at 3rd row, 1st column, Zx-shearing. 
element at 3rd row, 2nd column, zy-shearing. 
element at 3rd row, 3rd column, z-scaling. 
element at 3rd row, 4th column, z-shift. 


Comments: 


None 
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See also: 


None 
Return to the List of data structures 
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AEE3DVertex 


Description: 


This STRUCT defines the vertex used in the I3D API. Itincludes the location, color, and 
texture coordinates. It is also needed as an output for the function 
I3D ApplyModelViewTransform(). 


Definition: 
typedef struct | AEE3DVertex ( 

1nt32 x; 
int32 y; 
int32 z; 
intl6 vnorm x; 
intl6 vnorm y; 
intl6 vnorm Z; 
uint8 s; 
uint8 t; 

+ AEE3DVertex; 























Members: 
x,y,Z: Location (x,y,z). 
vnorm x, vnorm y, vnorm Z: The vertex normal. 
s;t: One set of normalized (0-255) texture coordinates. 
s is the horizontal coordinate. 
tis the vertical coordinate. 


Comments: 
None 


See Also: 
I3D ApplyModelViewTransform() 
I3D RenderTriangles() 
Return to the List of data structures 
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AEE DBError 


Description: 


Data Types 


This data structure indicates the error in OEMDB to the AEE layer. A pointer to this 
error type is passed to every OEMDB function and is populated by every OEMDB 






































































































































































































































function. 
Definition: 

typedef enum AEE DBError 
f 
AEE DB ERR NO ERR, 
AEE DB ERR NO MEMORY, 
AEE DB ERR BAD HANDLE, 
AEE DB ERR BAD RECID, 
AEE DB ERR BAD STATE, 
AEE DB ERR ALREADY EXIST, 
AEE DB ERR NOT EXIST, 
AEE DB ERR ALREADY OPEN, 
AEE DB ERR DB NOT OPEN, 
AEE DB ERR TOO MANY DB, 
AEE DB ERR TOO MANY RECORD, 
AEE DB ERR NO RECORD, 
AEE DB ERR UNKNOWN FORMAT, 
AEE DB ERR ABORTED, 
AEE DB ERR NO FS SPACE, 
AEE DB ERR BAD PATH, 
AEE DB ERR OTHER FS ERR, 
AEE DB ERR CANNOT INIT, 
AEE DB ERR BAD RECORD, 
AEE DB ERR NO RECINFO STRUCT, 
AEE DB ERR BAD NEW RECORD, 
AEE DB ERR NOT ALLOWED, 
AEE DB ERR NO RECBUF, 
AEE DB ERR MAX 
) AEE DBError; 

















Members: 


AEE DB ERR NO ERR 
AEE DB ERR NO MEMORY 
AEE DB ERR BAD HANDLE 
AEE DB ERR BAD RECID 
AEE DB ERR BAD STATE 


AEE DB ERR ALREADY EXIST 
AEE DB ERR NOT EXIST 
AEE DB ERR ALREADY OPEN 
AEE DB ERR DB NOT OPEN 
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DB is OK, operation succeeded. 

Not enough memory for this operation. 
DB handle is not valid. 

Record ID is not valid. 

DB in bad state; suggest closing and 
reopening. 

DB already exists (cannot create). 

DB does not exist (cannot open). 

DB is open already (cannot open/recover). 
DB is not open, and therefore cannot be 
closed. 


Data Types 


brew. 

AEE DB ERR TOO MANY DB Too many open DBs (cannot open). 

AEE DB ERR TOO MANY RECORD Too many records (cannot add record). 

AEE DB ERR NO RECORD No records in the database. 

AEE DB ERR UNKNOWN FORMAT | Unknown data file format. 

AEE DB ERR ABORTED DB operation is aborted (for example, in 
async operation). 

AEE DB ERR NO FS SPACE Not enough space in file system for the 
operation. 

AEE DB ERR BAD PATH DB exists in a path that is restricted. 

AEE DB ERR OTHER FS ERR General file system errors (other than no 
space). 

AEE DB ERR CANNOT INIT Cannot initialize database. 

AEE DB ERR BAD RECORD Specified record is invalid. 


AEE DB ERR NO RECINFO STRUCT No pointer to Reclnfo structure. 
AEE DB ERR BAD NEW RECORD New record to be added is invalid. 


AEE DB ERR NOT ALLOWED Requested operation is not allowed on the 
specified database (DB may be read only). 
AEE DB ERR NO RECBUF No record buffer is allocated for this 
database. 
AEE DB ERR MAX For range checking. 
Comments: 
None 
See Also: 
None 


Return to the List of data structures 
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AEE DBRecinfo 


Description: 
This data structure defines the record information. The OEM layer returns information 
on the record requested by OEM DBRecordGet. 


Definition: 
typedef structure AEE DBRecInfo 
f 
word wRecID; 
word wRecSize; 
dword dwLastModified; 
) AEE DBRecInfo; 























Members: 
wReclD ID of the record. 
wRecSize Size of the record (in bytes), excluding the header. 


dwLastModified Time when this record was last modified. 


Comments: 
None 


See Also: 
OEM DBRecordGet() 
Return to the List of data structures 
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AEEAppStart 


Description: 
This structure is sent on EVT APP START/EVT APP RESUME. 


Definition: 
typedef structure 

t 

int error; 
ABECLSID clsApp; 
IDisplay * pDisplay; 
ABEERect rc; 
const char * pszArgs; 
) AEEAppStart; 
































Members: 
error Filled by application, if there is an error. 
clsApp Applet ID. 
pDisplay Pointer to the IDisplay Interface object. 
rc Rectangle for the applet. 
pszArgs Pointer to character string of arguments. These arguments are also 
passed using the 
EVT APP BROWSE FILE/EVT APP BROWSE URL inputs. 
Comments: 
None 
See Also: 
AEERect 


Return to the List of data structures 
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AEEBitmaplInfo 


Description: 
This structure contains all of the information regarding the dimensions of a bitmap, for 
both DIB and DDB. 


Definition: 
typedef structure 


uint32 cx; 
uint32 cy; 
uint32 nDepth; 

+ AEEBitmapInfo; 














Members: 
CX Number of pixels per row. 
cy Number of pixel per column. 


nDepth Number of bits per pixel. 


Comments: 
None. 


See Also: 
None 
Return to the List of data structures 
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AEECallback 


Description: 


Data Types 


This structure specifies the data and functions for a callback registered with the 
ISHELL Resume() function. 


Definition: 
































typedef structure  AEECallback AEECallback;, structure | AEECallback 


í 














ABECallback * pNext; 


void * pmc; 
PENCBCANCEL pfnCancel; 
void * pCancelData; 
PFNNOTIFY pfnNotify; 
void * pNotifyData; 
void * pReserved; 





+; 


Members: 


pNext 
pmc 
pfnCancel 


pCancelData 


pfnNotify 


pNotifyData 
pReserved 


Comments: 
None 


See Also: 
None 





Reserved and the caller must not modify this member. 

Reserved and the caller must not modify this member. 

Pointer to the function called by the callback handler, if this callback 
is cancelled. The caller must set this pointer to NULL. 

Data passed to pfnCancel. The caller must not modify this member. 
This is the callback function that is invoked by AEE. The caller must 
set this pointer to the function to be called by the AEE callback 
handler. 

Data to be passed to pfnNotify. 

Reserved and this member is to be used by the callback handler. 


Return to the List of data structures 
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AEECallHistoryEntry 


Description: 


This struct contains the definition of each Call History entry Field. A Call History entry 
is a collection of one or more of these Fields. 


Definition: 
typedef struct AEECallHistoryEntry 
t 
AEECallHistoryField *pFields; 
uint16 wNumFields; 
+ AEECallHistoryEntry; 









































Members: 


pFields the array of fields 
wNumrFields number of fields in the array 


Comments: 
None 


See Also: 
AEECallHistoryField 
ICALLHISTORY. EnumNext() 
Return to the List of data structures 
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AEECallHistoryField 


Description: 
This struct contains the definition of each Call History entry Field. A Call History entry 
is a collection of one or more of these Fields. 


Definition: 
typedef struct AEECallHistoryField 

t 
ABEECLSID CisId 
uinti6 wID; 
uint16 wDataLen; 
void *pData; 
+ AEECallHistoryField; 



































Members: 

Clsld Class ID associated with the field ID. For predefined Fields, use a CIsID 

of O. 

wID Field ID (ex AEECALLHISTORY FIELD NAME) 

wDataLen Data Length 

pData Data (form and length varies according to wlD and Clsld) 
Comments: 

None 
See Also: 


AEECallHistoryEntry 
Return to the List of data structures 
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AEECameraNotify 


Description: 
This structure contains information of an event generated by ICamera object. Itis sent 
via the registered callback function. 


Definition: 
typedef struct AEECameraStatus ( 

ICamera * pCam; 
int 16 nCmd; 
int 16 nSubCmd; 
intl6 nStatus; 
int 16 nReserved; 
void * pData; 
uint32 dwSize; 
) AEECameraStatus; 























Members: 


pCam ICamera object originating this callback 
nCmd Command code. CAM CMD XXX 
nSubCmd Sub command code (see comments) 
nStatus Status code. CAM STATUS XXX 
nReserved Reserved field 

pData Context-based data 

dwSize Context-based data size 


Comments: 


fnCmd = CAM CMD SETPARM/CAM CMD GETPARM, then nSubCmd will be 
nParmilD (CAM PARM XXX). 


lfnCmd = CAM CMD START, then nSubCmd will be 
CAM MODE PREVIEW/CAM MODE SNAPSHOT/CAM MODE MOVIE. 


See Also: 
ICAMERA RegisterNotify() 
ICAMERA SetParm() 
ICAMERA GetParm() 
ICAMERA Start() 
Return to the List of data structures 
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AEEDevicelnfo 


Description: 


This structure contains mobile device information requested in 
ISHELL GetDevicelnfo() 


Definition: 


typedef struct 

f 
t16 cxScreen; 
t16 cyScreen; 
t16 cxAltScreen; 
t16 cyAltScreen; 
t16 cxScrollBar; 
t16 wEncoding; 
t16 wMenuTextScroll; 
t16 nColorDepth; 
ptyEnum unused2; 
t32 wMenulmageDelay 
t32 dwRAM; 
flg bAltDisplay:l; 
flg bFlip:l; 
flg bVibrator:1; 
flg bExtSpeaker:1; 
flg bVR:1; 
flg bPosloc:l1; 
flg bMIDI:L; 
flg bCMX:1; 
uint32 dwPromptProps; 
uintl6 wKeyCloseApp; 
uint1l6 wKeyCloseAllApps; 
uint32 dwLang; 
uintl6 wStructSize; / 
uint32 dwNetLinger; 
uint32 dwSleepDefer; 
uint16 wMaxPath; 
uint32 dwPlatformID; 
) AEEDeviceInfo; 
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Members: 
cxScreen Physical screen size (pixels) 
cyScreen Physical screen size (pixels) 
cxAltScreen Physical screen size of 2nd display 
cyAltScreen Physical screen size of 2nd display 
cxScroliBar Width of standard scroll bars 
wEncoding Character set encoding (AEE ENC UNICODE, ....) 
unused2 unused 
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wMenulmageDelay 
nColorDepth 


dwRAM 
bAIDisplay 
bFlip 

bVibrator 
bExtSpeaker 
bVR 

bPosLoc 

bMIDI 

bCMX 
dwPromptProps 
wkKeyCloseApp 
wkKeyCloseAIIApps 
dwLang 


Data Types 


Milliseconds that should be used for the delay 
Color Depth (1 = mono, 2 = grey, etc.) 


Total RAM installed (RAM) 

Device has an alternate display (Pager) 
Device is a flip-phone 

Vibrator installed 

External speaker installed 

Voice recognition supported 

Position location supported 

MIDI file formats supported 

CMX audio supported 

Default prompt properties 

Key to close current app 

Key to close all applications (AVK END is default) 
ISO defined language ID 


NOTE: In order to use the following fields, you MUST fill-in the wStructSize 
element of the structure before passing this to the GetDevicelnfo call. 


wStructSize 
dwNetLinger 
dwSleepDefer 


wMaxPath 


dwPlatformlD 


Comments: 


None 


See Also: 


None 


Size of the struct. Need to be filled for the following fields to work 
PPP Linger Time in milliseconds 


Time in milliseconds prior to the handset attempting to go into sleep 
mode 


Maximum length of the file name (including path name) supported on 
the device 


ID used to uniquely identify the device platform. 


Return to the List of data structures 
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AEEDeviceltem 


Description: 


Data Types 


This specifies the ID of the item whose information is needed. This is used in the 
function ISHELL GetDevicelnfoEx() 




































































Definition: 
typedef int AEEDeviceItem 
fdefine AEE DEVICEITEM CHIP ID 1 
ftdefine AEE DEVICEITEM MOBILE ID 2 
tdefine AEE DEVICEITEM AMR VOCODER SUPPORT 3 
tdefine AEE DEVICEITEM EVRC VOCODER SUPPORT 
tdefine AEE DEVICEITEM IS96 VOCODER SUPPORT 
tdefine AEE DEVICEITEM IS96A VOCODER SUPPORT 
tdefine AEE DEVICEITEM 1S733 VOCODER SUPPORT 
tdefine AEE DEVICEITEM SMV VOCODER SUPPORT 8 




















Members: 


The following Items are supported: 


AEE DEVICEITEM CHIP ID 


Description: 

















4 

o 
6 
7 


This returns a String identifying the ID of the chipset. For QUALCOMM 
chipsets, these strings are of the form: MSM3100, MSM3300, 
MSM5100, etc.This information is returned as a AECHAR when 
ISHELL GetDevicelnfoEx() is invoked with this ID. When this ID is 
passed to ISHELL GetDevicelnfoEx(), the following details apply: 


int ISHI 





ELI GetDeviceInfol 





Ex (IShell *po, 


nItem, void *pBuff, int *pnSize); 


Parameters: 


po: Pointer to the IShell object. 
nitem: Specifies AEE DEVICEITEM CHIP ID. 
pBuff. Buffer capable of holding a AECHAR string. 
pnSize: On input, this specifies the size of pBuff in bytes. On retum, *pnSize contains 
the actual size of pBuff filled by this function. If pBuff is NULL or smaller than the size 


needed, *pnSize is filled with the actual size needed by this function if pnSize is NULL 
on input, this function returns EBADPARM 


AEE DEVICEITEM USER 


AEE DEVICEITEM AMR VOCODER SUPPORT 


AEE DEVICEITEM EVRC VOCODER SUPPORT 
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AEEDeviceItem 





User defined or OEM defined 
items to begin after this 


Is AMR (Adaptive Multi-Rate) 


Vocoder Supported ? 


Is EVRC (Enhanced Variable 


Rate Codec) Vocoder 
Supported ? 


Erevi Data Types 


AEE DEVICEITEM 1596 VOCODER SUPPORT 


AEE DEVICEITEM IS96A VOCODER SUPPORT 


AEE DEVICEITEM 15733 VOCODER SUPPORT 


AEE DEVICEITEM SMV VOCODER SUPPORT 


AEE DEVICEITEM SYS COLORS DISP1 
AEE DEVICEITEM SYS COLORS DISP2 
AEE DEVICEITEM SYS COLORS DISP3 
AEE DEVICEITEM SYS COLORS DISP4 


Comments: 
None 


See Also: 
ISHELL GetDevicelnfoEx() 
Return to the List of data structures 
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Is QCELP-IS96(8K)(Qualcomm 
Code Excited Linear Predictive 
Coding) Vocoder Supported ? 
Is QCELP- 
|S96A(8K)(Qualcomm Code 
Excited Linear Predictive 
Coding) Vocoder Supported ? 
Is QCELP- 
1S733(13K)(Qualcomm Code 
Excited Linear Predictive 
Coding) Vocoder Supported ? 
Is Selectable Mode Vocoder 
Supported ? 

System color table for display 1 
System color table for display 2 
System color table for display 3 
System color table for display 4 


= Data Types 


AEEDNSClass 


Description: 


This is a 16-bit integer used to hold DNS "class" values. Valid values are those defined 
in Internet standards and supported by the server being queried. 


Definition: 
typedef int1l6 AEEDNSOType; 











Members: 
None 


Comments: 
None 


See Also: 
IDNS AddQuestion() 
Return to the List of data structures 
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AEEDNSItem 


Description: 


Data Types 


Each AEEDNSlItem structure describes either a DNS Question or a DNS Resource 


Record. 


Definition: 





typedef struct AEEDNSItem ( 


cons 
intl 








6 nType; 














AEEDNSCI 








int32 nTTL; 

















cons 
int32 chbData; 
) AEEDNSIt em; 
Members: 
pbyDomain 
nType 
nClass 
nTTL RR-only 
pbyData RR-only 
cbData RR-only 
Comments: 
None 
See Also: 
None 


t byte * pbyDomain; 


ABEDNSType nType; 
ass nClass; 


t byte * pbyData; 


The NAME field of the RR/Question record. This is given as a pointer into the 
response data, and is in the DNS format for domain names (possibly using 
header compression). Use IDNS ParseDomain() to obtain a zero-terminated 
string in dotted notation. 

The TYPE field of the RR/Question record. 


The CLASS field of the RR/Question record. 


32-bit TTL value. Treat as a signed 32-bit int; note that multiple 
records may have different TTLs, altough such server behavioy is 
not recommended. 


A pointer to the RDATA field of the RR record. Any domain names 
within this memory range can be decoded using 
IDNS ParseDomain(). 


Number of bytes in the RDATA record. Note that when pbyDatal] 
contains a domain name, cbData may be much smaller than the 
resulting zero-terminated domain name (due to DNS header 
compression.) 


Return to the List of data structures 
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AEEDNSResponse 


Description: 


AEEDNSResponse contains DNS response data. These items correspond directly to 
fields as described in the DNS protocol specification (RFC1035). 














Definition: 

typedef struct AEEDNSResponse ( 
uint16 uFlags; 
uint16 uReserved; 
int16 nQuestions; 
int16 nAnswers; 
int16 nServers; 
int16 nAdditional; 








AEEDNSItem * pQuestions; 
ABEDNSItem * pAnswers; 

ABEDNSItem * pServers; 
AEED 
) 


























EEDNSItem * pAdditional 
ABEEDNSResponse; 














Members: 

uFlags The flag field in the DNS message header 

uReserved The reserved field in the DNS message header 

nQuestions The number of "Question" records in the message 

nAnswers The number of "Answer" records in the message 

nServers The number of "Authority" or server records in the message 
nAdditional The number of "Additional" records in the message 
pQuestions The pointer to an array of AEEDNSItem structures describing 


Question records. The size of this array is given by nQuestions. 


The question records make use of only a few fields of the AEEDNS Item structure. The 
remaining fields are left zero or NULL. pAnswers, pServers, pAdditional are pointers to 
arrays of AEEDNSlItem structures describing Resource Records. The sizes of these 
array are given by nAnswers, nServes, and nAdditional, respectively. 


Comments: 
None 


See Also: 
AEEDNSItem 
Return to the List of data structures 
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AEEDNSType 


Description: 


This is a 16-bit integer used to hold DNS "type" values. Valid values are those defined 
in Internet standards and supported by the server being queried. 


Definition: 
typedef intl6 AEEDNSType; 











Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEEFilelnfoEx 


Description: 


Data Types 


AEEFilelnfoEx is used to contain extended information associated with a file. 


Definition: 





typedef struct  FileInfoEx 


( 


int nStructSize; 

char attrib; 

uint32 dwCreationDate; 
uint32 dwSize; 

char * pszFile; 

int nMaxFile; 


õ 














n 





=>» 








ECHAR * pszDescription; 
t nDescriptionSize; 
BECLSID * pClasses; 
t nClassesSize; 
AEEFileInfoEx; 








Members: 


nStructSize 
attrib 
dwCreationDate 
dwSize 
pszName 


nMaxName 
pszDescription 
nMaxDescription 
pClasses 
nMaxClasses 


Comments: 
None 


See Also: 
Filelnfo 


Size of the structure 

File attributes specified by FileAttrib 
File creation date 

File size 


ASCIIZ name to be filled with the file name of max length 
nMaxName 


Maximum size of name field filled 

Wide string description of the file with max size of nMaxDescription. 
Size in bytes of description 

List of AEECLSIDs that own/use this file 

Size in bytes of pClasses list 


Return to the List of data structures 
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AEEFileUselnfo 


Description: 
AEEFileUselnfo is used to contain the file usage information. 


Definition: 
typedef struct  AEEFileUseInfo 














uintl6 wMaxFiles; 
uint1l6 wFilesUsed; 
uint32 dwMaxSpace; 
uint32 dwSpaceUsed; 
) AFEEFileUseInfo; 














Members: 
wMaxFiles Maximum number of files in EFS this Module is allowed to create 
wFilesUsed Number of files currenty used by this Module 
dwMaxSpace Maximum EFS Space this module is allowed to consume 


dwSpaceUsed Total space currently used by this module so far 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEEFontinio 


Description: 


This structure describes characteristics of a font. Character cell height and baseline 
offset are properties of a font; the values do not changed from character to character 
within a font. 


Each character's graphical representation is bounded by a rectangle called a character 
cell. The height of this cellis a property of the font, and cell widths can vary from 
character to character. When text is drawn opaquely, each character's cellis drawn to 
a same-sized rectangle in the destination bitmap, in which the pixels are set to either 
the background color or the foreground color. When a character is drawn transparently, 
only the foreground pixels are drawn, and pixels that would otherwise take on the 
background color are left unchanged. 


Afont's baseline is important for readability when different fonts are used on the same 
line of text. The baseline divides the character cell into descent and ascent areas. The 
descent area contains character desenders -- portions of a glyph that extend below the 
bottom of most characters -- and any spacing included at the bottom of the character 
cell. When different fonts are used on the same line of text, knowledge of the location 
of the baseline within the character cell allows the application to align the baselines by 
adjusting the vertical positioning of the characters. 


This figure shows two adjacent character cells from a single font, illustrating how 
nAscent and nDescent relate to the baseline and the height of the font: 


=>>RK=—————— | 

== d-———== | 

=X-——X-——X- | ascent = 7 
-XXXXX-——x— | 

=X---K-——X- | 
=X-=-X-==--X— "| 00 húaseline 
—>———————— X-— | 

XX | descent = 3 





total height = ascent + descent=7 + 3=10 


Definition: 


typedef struct 
f 
int16 nAscent; 
int16 nDescent; 
) AEEFont Info; 














Members: 
nAscent Maximum number of pixels that font extends above the baseline. 
nDescent Maximum number of pixels that font extends below the baseline. 
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Comments: 
This structure may be extended in the future by adding new fields to the end. 


See Also: 
IFONT Getinfo() 
Return to the List of data structures 
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Data Types 


AEEGPSConfig 


This structure is used to configure the GPS engine provided by this interface. 


typedef struct AE 












































EGPSConfig ( 
PSMode mode; 

16 nFixes; 

16 nInterval; 

PSOpt optim; 

PSQos gos; 

PSServer server; 














Description: 
Definition: 
AEEG 
uint 
uint 
AEEG 
AEEG 
AEEG 
*+ AE 
Members: 
mode 


EGPSConfig; 


The mode of operation to be configured for this interface 


Possible options are: 
AEEGPS MODE ONE SHOT 


AEEGPS MODE DLOAD FIRST 


AEEGPS MODE TRACK LOCAL 


Only one position determination 
request to be made. This option may 
not be optimal for repeated position 
determination requests. 


This mode is suited for applications 
that would do repeated position 
determination requests, and would 
prefer the results to be computed 
locally on the mobile device after 
initial data is downloaded from the 
server. 


This mode is suited for 
applications intending to perform 
tracking, and require frequent 
fast location/velocity/ altitude 
information. This mode also 
requires minimizal requests to 
the network for position 
determination information. 


AEEGPS MODE TRACK NETWORK This mode is suited for 


AEEGPS MODE DEFAULT 
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applications requiring tracking 
that would prefer getting 
accurate position determination 
information from the network. 
The default mode of operation, 
which is set to 
AEEGPS MOD DLOAD FIRST 


brew. 


nFixes 


ninterval 
optim 


qos 


server 


Comments: 
None 


See Also: 
None 


Data Types 


Estimated number of position determination requests that would be made 
using this interface. 

Estimated interval between fixes (in seconds). 

The optimization required for this interface. 


Possible values are: 

AEEGPS OPT SPEED: Optimize for speed 

AEEGPS OPT ACCURACY: Optimize for accuracy. 

AEEGPS OPT DEFAULT: Default. Set for speed optimization. 
Quality of service values between 1-255 are valid, 255 providing the highest 
quality of service. This option may be ignored on certain mobile devices. 
Server configuration specifies the server type and configuration. Possible server 
types are: 

AEEGPS SERVER DEFAULT 

AEEGPS SERVER IP 

AEEGPS SERVER DBURST 


lfthe server type is AEEGPS SERVER IP, the IP Address and port of the 
Position Determination server must be specified. 


Return to the List of data structures 
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AEEGPsSInfo 


Description: 


This structure is used to obtain GPS based position location information from the 
system. The parameters returned are as per the TIA/EIA IS-801 standard. 


Definition: 
typedef struct | AEEGPSInfo ( 
uint32 dwTimeStamp; 
uint32 status; 
int32 dwLat; 
int32 dwLon; 
intl6 wAltitude; 
t16 wHeading; 
t16 wVelocityHor; 
8 bVelocityVer; 
ABEEGPSAccuracy accuracy; 
t16 fValid; 
t8 bHorUnc; 
t8 bHorUncAngle; 
t8 bHorUncPerp; 
t16 wVerUnc; 
REGPSInfo; 
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Members: 
dwTimeStamp: Time (in seconds since 1/6/1980) of this measurement 
status: Response Status 
dwLat: Latitude, 180/2125 degrees, WGS-84 ellipsoid 
dwLon: Longitude, 360/2226 degrees, WGS-84 ellipsoid 
wAltitude: Altitude, meters, WGS-84 ellipsoid 
wHeading: Heading, 360/2"10 degrees 
wVelocityHor: Horizontal velocity, 0.25 meters/second 
bVelocityVer: Vertical velocity, 0.25 meters/second 
accuracy: Accuracy of the data. 
fValid: Flags indicating valid fields in the struct. 
bHorUnc: Horizontal uncertainity 
bHorUncAngle: Horizontal uncertainity at angle 
bHorUncPerp: Horizontal uncertainty perpendicular 
bVerUnc: Vertical uncertainity 


Comments: 
fValid indicates the fields set in the AEEGPSInfo structure. The following 
flags are available. 
AEEGPS VALID LAT: Valid latitude 
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AEEGPS VALID LON: Valid longitude 
AEEGPS VALID ALT: Valid altitude 
AEEGPS VALID HEAD: Valid heading 
AEEGPS VALID HVEL: Valid horizontal velocity 
AEEGPS VALID VVEL: Valid vertical velocity 
AEEGPS VALID HUNC: Valid horizontal uncertainity 
AEEGPS VALID AUNC: Valid Horizontal uncertainity at angle 
AEEGPS VALID PUNC: Valid horizontal uncertainity (orthogonal) 
The accuracy is specified by 6 levels starting ffom AEEGPS ACCURACY LEVEL1 


See Also: 
None 
Return to the List of data structures 
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AEEGSM1xSig NotifyMessageType 


Description: 


A pointer to AEEGSM1xSig NotifyMessageType struct is sent as dwParam member 
of the EVT NOTIFY event when an application registers for 
NMASK GSM1xSIG PROTOCOL TYPE notification. 


Definition: 
typedef struct ( 
AEEGSMixSig NotifyMessageTypeEnum messageType; 
































union ( 
AEEGSMixSig SignalingMessageType *signalMessage; 
AEEGSMixSig RejecMessageType *rejectMessage; 
) msg; 

















+ AEEGSMixSig NotifyMessageType; 


Members: 


messageType Indicates the type of message viz. Signaling or Reject 
msg.signalMesage Contains the signaling payload. 


msg.rejectMessage Contains the reject payload. 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEEGSM1xSig RejectMessageType 


Description: 


AEEGSM1xSig RejectMessageType is used to send out a GSM1x Signaling Reject 
message to the network using IGSM1xSig SendSignalingReject(). 


Definition: 
typedef struct ( 
byte ProtocolTypeRejected; 
byte RejectCauseLength; 
byte RejectCause [GSMixSIG REJECT MAX]; 
+) AEEGSMixSig RejectMessageType; 


























Members: 


ProtocolTypeRejected Protocol Type that is rejected. This is a 4 bit value 
RejectCauseLength Length of the Reject Cause fields 
RejectCause Holds the Reject Cause information 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEEGSM1xSig SignalingMessageType 


Description: 


AEEGSM1xSig SignalingMessageType is used to send out a GSM1x Signaling 
Message using IGSM1xSig SendSignalingMessage() 


Definition: 
typedef struct ( 
byte ProtocolRevision; 
byte ProtocolType; 
byte ProtocolDataLen; 
byte ProtocolData [GSMlxSIG SIGNALING MAX]; 
+ AEEGSMixSig SignalingMessageType; 

















Members: 
ProtocolRevision 4 bit field specifiying the Protocol Revision of GSM1x Sig Msg 
ProtocolType 4 bit field specifying the Protocol Type of GSM1x Sig Msg 
ProtocolDataLength Length of the protocl type specific field length 
ProtocolData Array holding the Protocol Type Data 
Comments: 
None 
See Also: 


IGSM1xSig SendSignalingMessage() 
Return to the List of data structures 
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AEEGSM1xControl statusType 


Description: 
AEEGSM1xControl statusType is sent as dwParam member of the EVT NOTIFY 
event when an application registers for NMASK GSM1xSIG STATUS CHANGE 


notification. This enum is also returned when applications call 
IGSM1xSig GetStatus(). 
























































































































































































































































































































































Definition: 
define AEEGSMIXCONTROL STATUS SUCCESS (0x0000) 
define AEEGSMIXCONTROL STATUS NO CARD (0x0001) 
define AEEGSMIXCONTROL STATUS NO INFO ON CARD (0x0002) 
define AEEGSMIXCONTROL STATUS MODE NOT SUPPORTED (0x0003) 
define AEEGSMIXCONTROL STATUS NAM SELECTION FAILED (0x0004) 
define AEEGSMIXCONTROL STATUS BUF TOO SMALL (0x0005) 
define AEEGSMIXCONTROL STATUS FIELD UNINITIALIZED (0x0006) 
define AEEGSMIXCONTROL STATUS VALUE OUT OF RANGE (0x0007) 
define AEEGSMIXCONTROL STATUS INVALID POINTER (0x0008) 
define AEEGSMIXCONTROL STATUS GSM1IX NOT SUPPORTED (0x0009) 
define AEEGSMIXCONTROL STATUS CANNOT READ FROM UIM (0x000A) 
define AEEGSMIXCONTROL STATUS CANNOT WRITE TO UIM (0x000B) 
define AEEGSMIXCONTROL STATUS FAILURE NV WRITE (0x000C) 
define AEEGSMIXCONTROL STATUS FAILURE NV READ (0x000D) 
define AEEGSMIXCONTROL STATUS FAILURE NAM SELECT (0x000E) 
define AEEGSMIXCONTROL STATUS INVALID DATA GSM DF (0x000F') 
define AEEGSMIXCONTROL STATUS INTERNAL ERROR (0x0010) 
define AEEGSMIXCONTROL STATUS INVALID PARAMETER (0x0011) 
define AEEGSMIXCONTROL STATUS INVALID INFO IN NV (0x0012) 
define AEEGSMIXCONTROL STATUS INVALID PRL (0x0013) 
define AEEGSMIXCONTROL STATUS COULD NOT CREATE IPHONE (0x0014) 
define AEEGSMIXCONTROL STATUS CANNOT SET DESIRED MODE (0x0015) 
define AEEGSMIXCONTROL STATUS INVALID MODE (0x0016) 
Members: 
None 
Comments: 
None 
See Also: 
None 


Return to the List of data structures 
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Data Types 


AEELogBinMsgType 


Description: 


This represents the structure of the log data when using brew log type 
AEE LOG TYPE BIN MSG as defined above. ILOGGER PutMsgy() fills this 
structure using its function arguments. 


Definition: 





typedef PACKED struct( 


uin 
uin 
uin 


t8 header; 
t32 line; 
t32 args [ MAX LOG TYPE BIN MSG ARGS J]; 























char pszMsg[ MAX LOG TYPE BIN MSG TEXT SIZE J]; 


+ AE 


Comments: 


header 


line 
args 
pszMsg 


See Also: 
None 

















ELogBinMsgType; 


bT7,b6 - bits reserved 

b5,b4 - number of args 

b3 bit - file name present 

b2,b1,b0 - message level 

line number in the log bucket where this log item was sent 

array containing at most MAX LOG TYPE BIN MSG ARGS 
pszMsg contains two consecutive NULL terminated strings. The first if 
the file name where the log message was sent, and the second is an 


ASCII text message. The maximum size of this element is 
MAX LOG TYPE BIN MSG TEXT SIZE. 


Return to the List of data structures 
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AEELogBucketType 


Description: 


Each log item is placed in one of 255 log buckets. By assigning a log bucket to each 
log item the post parser is able to filter based on the bucket. Log items may be 
seperated into subsystems, log types, etc... 






































Definition: 
typedef uint8 AEELogBucketType; 
tdefine AEE LOG BUCKET FIRST O 
tdefine AEE LOG BUCKET LAST 255 
Comments: 


How these buckets are used is up to the application developer 


See Also: 
None 


Return to the List of data structures 
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AEELogltemType 


Description: 


These are the different log types that distinguish the structure of the data contained in 
the log item. AEE LOG TYPE USER BASE and above are available for application 
developers to define thier own log data formats. The application developer is 
responsible for eleminating any conflicts that may arrise due to multiple applications 
using the same log type. 






























































Definition: 
typedef uint16 AEELogItemType; 
tdefine AEE LOG TYPE TEXT 0x000 
fdefine AEE LOG TYPE BIN MSG 0x001 
fdefine AEE LOG TYPE BIN BLK 0x002 
fdefine AEE LOG TYPE USER BASE 0x100 
Comments: 
Predefined log item types include: 
AEE LOG TYPE TEXT ASCII text message 


AEE LOG TYPE BIN MSG —AEELogTypeBinMsg 
AEE LOG TYPE BIN BLK | binary data block 


A user defined log item type 


AEE LOG TYPE USER BASE User must define own type structure for each user 
type they use 


See Also: 
None 
Return to the List of data structures 
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AEELogParamType 
Description: 
Possible parameters available to configure the ILOGGER interface or to get 
information concerning the current state of the ILOGGER interface. In addition to the 
list below, there may be OEM specific log parameters which will numerically start after 
AEE LOG PARAM LAST. See the specific implementation header files for more 
information. 
Definition: 
typedef uint16ô AEELogParamType 
AEE LOG PARAM INSTANCE ID 0x001 InstancelD is a developer defined ID number 
that can be used as the developer wishes. 
Possible uses are to distinguish between 
different application thread, or different 
application run-time states. Default instance 
ID is zero 
AEE LOG PARAM FILTER ONE 0x002 Filter a single log bucket 
AEE LOG PARAM FILTER BLOCK 0x003 sets filters for a block of 32 buckets 
AEE LOG PARAM SENT 0x004 Number of packets sent by an instance of 
ILOGGER 
AEE LOG PARAM DROPPED 0x005 Number of packets dropped by an instance 


of ILOGGERDropeed packets do not include 
packets that have been filtered. 


AEE LOG PARAM FILE FLUSH 0x006 Flushes the current log file and resets file 
pointer to beginning of file. May only be used 
with AEECLSID LOGGER FILE 


AEE LOG PARAM FILE MAX SIZE 0x007 Sets the maximum size the log file may 
become efaults to 1/2 the free EFS space. 
May only be used with 
AEECLSID LOGGER FILE 


AEE LOG PARAM FILE FREE SPACE 0x008 'Amountoffree space left in the log file before 
it reaches the maximum size set with the 
AEE LOG PARAM FILE MAX SIZE 
parameter May only be used with 
AEECLSID LOGGER FILE 


AEE LOG PARAM FILE NEW 0x009 'Closes the current log file and creates a new 
one using the specified name May only be 
used with AEECLSID LOGGER FILE 


AEE LOG PARAM LAST 0x100 | This must be the last defined param type 
OEM specific parameters start at this value, 
See the specific implementation header files 
for more information. 
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Comments: 
The following tables describes the parameter usage: 


AEE LOG PARAM INSTANCE ID 
SetParam: param - New instance ID, 
pParam - None 
GetParam: pParam - Address of memory location to place current instance ID 
AEE LOG PARAM FILTER ONE 


SetParam: param - Log bucket to filter, must be greater then O and less then 
AEE LOG BUCKET LAST 


pParam - Boolean value indicating weather to turn bucket on or off, TRUE 
turns bucket on 


All buckets are off by default 
GetParam: pParam - None 
AEE LOG PARAM FILTER BLOCK 
SetParam: param - Which block of filters to set where O is the first block and param 
must be less then AEE LOG NUM BUCKET BLOCKS 
pParam - 32 bit value to set block to. Each bit represents one bucket 


GetParam: pParam - When calling which block to get where O is the first block, on 
return the requsted 32 bit block 


AEE LOG PARAM SENT 
SetParam: param - Number to preset sent count with, or zero to reset count, 
pParam - None 


GetParam: pParam - Address of memory location to place current number of 
packets sent 


AEE LOG PARAM DROPPED 
SetParam: param - Number to preset dropped count with, or zero to reset count, 
pParam - None 


GetParam: pParam - Address of memory location to place current number of 
packets dropped 


AEE LOG PARAM FILE FLUSH 
SetParam: param - None 
pParam - None 
GetParam: Not supported 
AEE LOG PARAM FILE MAX SIZE 
SetParam: param - New maximum log file size, 
pParam - none 


GetParam: pParam - address of memory location to place current maximum log 
file size 
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AEE LOG PARAM FILE FREE SPACE 
SetParam: Not supported 
GetParam: pParam - address of memory location to place remaining free space in 
log file 
AEE LOG PARAM FILE NEW 
SetParam: param - File mode: OFM READWRITE or OFM APPEND, 
pParam - string containing name of new log file 
GetParam: Not supported 
*AEE LOG PARAM FILE NEW must be used to create new file but any other file 
management must be done by the developer using IFILEMGR and IFILE. 
See Also: 


None 
Return to the List of data structures 
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AEELogRcdHdrType 


Description: 
Standard BREW log header version 2 
This header is appended to the beginning of each outgoing 
log packet. 


Definition: 

typedef PACKED struct( 
AEELogVerHdrType verHdr; 
int32 upTime; 
EBECLSID classID; 
intê instanceID; 
EELogBucketType bucket; 
EELogltemType type; 
ABELogRcdHdrType; 









































-22GRS 











Comments 


verHdr Version and packet length information of the BREW log record header 

upTime Number of milliseconds since the devices was powered on as returned 
by the BREW helper function GETUPTIMEMS(). 

classiD Class ID of the currently running application 

instancelD Developer defined uint8 ID number that can be used as the developer 
wishes. Possible uses are to distinguish between different application 
thread, or different application run-time states. 


bucket AEELogBucketType Logging bin number (word8) 
type AEELogltemType Log type (word 16) 

See Also: 
AEELogBucketType 


AEELogltemType 
Return to the List of data structures 
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AEELogVerHdrType 


Description: 


Starting with header version 2 and above this version header will always come first in 
the BREW log packet (this does not include any transport medium headers such as the 
serial packet headers). This version header defines the version of the following BREW 
header (AEELogRcdHdrType) and the size of this entire BREW packet (not including 
transport medium headers). 


Definition: 
typedef PACKED struct( 
uint8 version; 
uintl6 length; 
+ AEELogVerHdrType; 

















Comments: 
version uintê Log record header version (AEE LOG VERSION) 
length Length of this entire uint16 BREW log packet 

See Also: 
None 


Return to the List of data structures 
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AEEMedia 


Description: 
This structure defines the data members common across all IMedia-based classes. 


Definition: 
typedef struct | AEEMedia 
( 
INHERIT AEEMedia (IMedia); 
) AEEMedia; 






































Members: 
INHERIT AEEMedia(IMedia): A macro that declares the following members. 
DECLARE VTBL(iname): Declares the virtual table of the class 
m pIShell: Pointer to IShell 
m nRefs: Reference count 
m clsSelf: Class ID of the IMedia 
m nState: State of the media 
m bStateChanging: = TRUE, means IMedia is in state transition 
m md: Media data source/sink 
m pfnNotify: User registered callback function 
m pUser: User data passed when m pfnNotify() is called 
m pszFile: Full path of the file name 


Comments: 


This structure is inherited by all the derived classes. Derived classes can directly use 
the AEEMedia functions defined in this file if they inherit ftom structure and also can 
use AEEMedia functions in their vtbls. 


See Also: 
None 
Return to the List of data structures 
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AEEMediaCallback 


Description: 


This structure defines IMedia-specific callback info structure wrapped around 
AEECallback and IMedia callback info structures. 


Definition: 
typedef struct | AEEMediaCallback 
f 


int bInUse; 









































AEECallback cb; 
AEEMediaCmdNotify cmdNotify; 
+ AEEMediaCallback; 
Members: 
bInUse Callback/Command availability; = TRUE, means this structure is in use. 
cb Pre-loaded and does not change 
cmdNotify IMedia callback-specific info 
Comments: 


This structure is typically used by all the derived classes. 


See Also: 
AEEMedia CallbackNotify() 
Return to the List of data structures 
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AEEMediaCmdNotify 


Description: 


This structure is contains information regarding the event returned by IMedia through 
an applet-registered callback. 


Definition: 

typedef structure 

f 

AEECLSID clsMedia; 
IMedia * pIMedia; 
int nCmd; 
int nSubCmd; 
int nStatus; 
void * pCmdData; 
uint32 dwSize; 
+ AEEMediaCmdNotify; 


























Members: 
clsMedia CLSID of IMedia concrete class. 
pIMedia Pointer to IMedia. 
nCmd Command code. 
nSubCmd Subcommand code, if any or O (zero). 
nStatus Status code. 
pCmdData Contains one of the values listed above. 
dwSize Size of pCmdData. 

Comments: 


The following table gives the possible events that contain command, subcommand, 
status, and context sensitive data: 








pData 

nCmd nSubCmd nStatus [optional] 
MM CMD SETMEDIA MM PARM XXX MM STATUS DONE <Depends 
PARM (See on parm> 

IMEDIS SetMediaParm 

0) 

MM STATUS ABORT 

MM CMD GETMEDIA MM PARM XXX MM STATUS DONE <Depends 
PARM (See on parm> 


IMEDIA GetMediaParm 
0) 


MM STATUS ABORT 





MM CMD PLAY 0 MM STATUS START 
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MM STATUS DONE 
MM STATUS ABORT 





MM STATUS MEDIA SP [Ptrto 

EC MediaSpe 
c] 

MM STATUS TICK UPD 

ATE 

MM STATUS DATA IO D Elapsed 

ELAY Time in 
MS 

MM STATUS SEEK [Elapsed 
Time in 
MS] 

MM STATUS SEEK FAIL 

MM STATUS PAUSE Elapsed 
Time in 
MS 

MM STATUS PAUSE FAI 

L 

MM STATUS RESUME Elapsed 
Time in 
MS 

MM STATUS RESUME F 

AIL 

MM STATUS REPEAT [Elapsed 
Time in 
MS] 

MM CMD RECORD 0 MM STATUS START 

MM STATUS DONE 

MM STATUS ABORT 

MM STATUS MEDIA SP Ptrto 

EC MediaSpe 
c 

MM STATUS TICK UPD 

ATE 

MM STATUS DATA IO D [Elapsed 

ELAY Time in 
MS] 

MM STATUS SEEK [Elapsed 
Time in 
MS] 
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MM STATUS SEEK FAIL 





MM STATUS PAUSE [Elapsed 
Time in 
MS] 
MM STATUS PAUSE FAI 
L 
MM STATUS RESUME [Elapsed 
Time in 
MS] 
MM STATUS RESUME F 
AIL 
MM STATUS SPACE WA 
RNING 
MM STATUS SPACE ER 
ROR 
MM CMD GETTOTAL O MM STATUS DONE Total Time 
TIME in MS 


MM STATUS ABORT 


See Also: 
PFNMEDIANOTIFY 
IMEDIA SetMediaParm() 
IMEDIA GetMediaParm() 
IMEDIA Play() 
IMEDIA Record() 
IMEDIA GetTotalTime() 
Return to the List of data structures 
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AEEMediaData 


Description: 


This structure defines the stream type and context sensitive data associated with the 
media data. 


Definition: 
typedef structure ( 
AFECLSID clsData; 
void * pData; 
uint32 dwSize; 
) AFEEMediaData; 


























Members: 


clsData Type of Stream. 
pData Context sensitive data. 
dwSize Context sensitive data. 


Comments: 


Following table gives details of context sensitive data for predefined stream types. 
Read/Write means Playback/Record. 





clsData Mode pData dwSize 
MMD FILE NAME Read/Write File name 0 

MMD BUFFER Read/Write Buffer pointer data size or O 
MMD ISOURCE Read only ISource * data size or O 


For playback, cls can be set to CLSID of any ISource-based class with pData set to 
the corresponding interface pointer. 


For recording, only MMD FILE NAME/MMD BUFFER types are allowed. Existing file 
name or memory buffer will be overwritten. 


See Also: 
None 
Return to the List of data structures 
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AEEMediaMIDISpec 


Description: MIDI format specification 


Definition: 
typedef struct AEEMediaMIDISpec 
f 
byte nFormat; 
uint1l6 nTracks; 
int16 nDivision; 
+ AEEMediaMIDISpec; 























Members: 
nFormat SMF format 0, 1 or2 
nTracks Number of tracks in the SMF 
nDivision Timing info 

Comments: 


This structure is optionally retumned in MM MEDIA SPEC callback by IMedia object 
handling MIDI format. 


See Also: 
IMEDIA Play() 
Return to the List of data structures 
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AEEMediaMP3Spec 


Description: MP3 format specification 


Definition: 
typedef struct AEEMediaMP3Spec 

f 
int nVersion; 
byte nLayer; 
boolean bCRCFlag; 
uintl6 wBitRate; 
uint32 dwSampleRate; 
byte nChannel; 














byte nExtension; 
boolean bCopyrightFlag; 
boolean bOriginalFlag; 
byte nEmphasis; 





char szTitle[MM MP3 ID3 TAG LENGTH] 
char szArtist [MM MP3 ID3 TAG LENGTH]; 
char szAlbum[MM MP3 ID3 TAG LENGTH] 
char szYear[4]; 
































char szComment [MM MP3 ID3 TAG LENGTH]; 
byte nGenre; 
+ AEEMediaMP3Spec; 




















Members: 
nVersion MPEG version 
nLayer MPEG layer compression: 1,2 or 3 
bCRCFlag TRUE, if CRC protection 
wBitRate Bit rate [Kilo bits] 
dwSampleRate Sampling rate [Kilo bits] 
nChannel Channel 
nExtension Only when JOINT STEREO 
bCopyrightFlag TRUE, if copyrighted 
bOriginalFlag TRUE, if original 
nEmphasis Audio emphasis 
szTitle Song title 
szArtist Song performer 
szAlbum Album with the song 
szYear Year Album released 
szComment Text comment 
nGenre ID3 genre tag 
Comments: 


This structure is optionally retumed in MM MEDIA SPEC callback by IMedia object 
handling MP3 format. 
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See Also: 


IMEDIA Play() 
Return to the List of data structures 
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AEEMediaSeek 


Description: 
This enum specifies the seek reference in IMEDIA Seek() API. 


Definition: 
typedef enum AEEMediaSeek 


f 
MM SEEK START = 0, 


MM SEEK END, 


MM SEEK CURRENT 
; AFEEMediaSeek; 


















































Members: 
MM SEEK START: Seek from the beginning of media 
MM SEEK END: Seek from the end of media 
MM SEEK CURRENT: Seek from the current position of the media 


Comments: 
IMEDIA Rewind() and IMEDIA FastForward() use MM SEEK CURRENT. 


See Also: 
IMEDIA Seek() 
IMEDIA Rewind() 
IMEDIA FastForward() 
Return to the List of data structures 
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AEENotify 


Description: 


A pointer to this structure is passed as dwParam when EVT NOTIFY event is sent to 
an application. An application receives this event as part of the notification(s) for which 
ithas registered. 


Definition: 
typedef structure 





t 

AEECLSID cls; 
INotifier * pNotifier; 
uint32 dwMask; 
v 
A 
) 





oid * pData; 
EENotifyStatus st; 
AEENotify; 


























Members: 


cls Notifier class. 
pNotifier Notifier object that issued the notification. 
dwMask Mask of bits that occurred. 


pData Notification-specific data. 

st Indicates to IShell, if the application processed the notification. 
Comments: 

None 
See Also: 


ISHELL RegisterNotify() (See the BREW API Reference Guide.) 
ISHELL Notify() (See the BREW API Reference Guide.) 

AEE NotifyStatus 

Return to the List of data structures 
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AEE NotifyStatus 


Description: 


This enumerated type defines the notification status values that are returned to the 
shell by an applet that receives a notification. The applet returns the status of its 
processing of the notification by setting the st member of the AEENotify structure it is 
passed along with theEVT NOTIFY event. 


Definition: 
typedef enum 
( 
NSTAT PROCESSED, 
NSTAT IGNORED, 
NSTAT STOP 
+ AEENotifyStatus; 


























Members: 

NSTAT PROCESSED The applet successfully processed the notification. 

NSTAT IGNORED The applet ignored the notification. 

NSTAT STOP The applet processed the notification, and the notification 
cannot be sent to any other applets that have registered to 
be notified of this event. 

Comments: 

None 

See Also: 


ISHELL RegisterNotify() (See the BREW API Reference Guide.) 
ISHELL Notify() (See the BREW API Reference Guide.) 
AEENotify 

Return to the List of data structures 
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AEEOrientationinto 


Description: 


This structure 


Definition: 











typedef struct  AEEOrientationInfo ( 
uintl6 wSize; 
uint32 dwTimeStamp; 
uint16 fValid; 
uint16 wAzimuth; 
uint16 wReservedl; 
uint16 wReserved2; 
) AEEOrientationInfo; 

















Members: 


wSize size of the data structure AEEOrientationInfo. 
dwTimeStamp Time (in seconds since 1/6/1980) of this measurement 
fValid Flags indicating valid fields in the struct. 

wAzimuth Angle O - 359 degress and 59 arcminutes. 


bits 0-5 contain arcminutes 
bits 6-15 contain degrees. 
This is the heading angle in the local horizontal plane measured 
clockwise from true North 
wReserved1 Reserved for support of tilt (pitch and roll) 
wReserved2 Reserved field. 


Comments: 


None 


See Also: 


IPOSDET GetOrientation() 
Return to the List of data structures 
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AEE ObjectHandle 


Description: 
Object handle returned by AEEObjectMgr Register() API. 


Definition: 
typedef uint32 AEEObjectHandle 


Members: 
None 


Comments: 
Following registration, use the object handle to get the object pointer. 


See Also: 
None 
Return to the List of data structures 
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AEEParminfo 


Description: 
This structure specifies finite equally spaced discrete values. 


Definition: 
typedef struct AEEParminfo 

f 

int32 nMin; 

int32 nMax; 

int32 nStep; 

int32 nDefault; 
int32 nCurrent; 

) AEEParmInfo; 


























Members: 
nMin Minimum value 
nMax Maximum value 
nStep Increment/Decrement steps 
nDefault Default value 
nCurrent Current value 
Comments: 
None. 
See Also: 
None 


Return to the List of data structures 
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AEEPosAccuracy 


Description: 
This data structure describes the Position Location Information Accuracy. 


Definition: 
typedef enum 








EE ACCURACY LOW, 
EE ACCURACY MED, 
EE ACCURACY HIGH 
ALEPosAccuracy; 























-Dpp- 














Members: 
None 


Comments: 
The position location information precision is directly related to the time it takes to 
satisfy the ISHELL GetPosition() request. 


See Also: 
ISHELL GetPosition() 
Return to the List of data structures 
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AEEPositioninto 


Description: 
This data structure describes thePosition Location Information 


Definition: 
typedef structure 
( 
int32 dwLat; 
int32 dwLon; 
uint32dwTimeStamp; 
) AEEPositionInfo; 

















Members: 
dwLat Latitude, 180/2125 degrees, WGS-84 ellipsoid. 
dwLon Longitude, 360/2126 degrees, WGS-84 ellipsoid. 


dwTimeStamp Time Stamp, seconds since 1/6/1980. 


Comments: 
None. 


See Also: 
ISHELL GetPosition() 
Return to the List of data structures 
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Data Types 


This ENUM specifies the raster operation for bit-block transfers of bitmaps, and 
drawing images on the screen with the functions in the Ilmage Interface. 


Definition: 
typedef enum 





E RO OR, 

E RO XOR, 
E RO COPY, 
E RO NOT, 
E RO MASK, 
E RO MERGENOT, 

E RO MASKNOT, 

E RO TRANSPARENT, 
E RO TOTAL 
ABERaster0Op; 







































































-“DPPpPppPppopprpDrprr- 














Members: 
NOTE: 


AEE RO MASK is deprecated; use AEE RO OLDTRANSPARENT instead. 
AEE RO MASKNOT is deprecated; use AEE RO ANDNOT instead. 
AEE RO TOTAL is not a raster operation in itself but important to list here. 


AEE RO OR 

AEE RO XOR 
AEE RO COPY 

AEE RO NOT 

AEE RO OLDTRANSPARENT 


AEE RO MERGENOT 
AEE RO ANDNOT 
AEE RO TRANSPARENT 


AEE RO TOTAL 


SRC .OR. DST*. 

SRC .XOR. DST*. 

DST = SRC*. 

DST = (ISRC). 

Same as AEE RO TRANSPARENT. In 
monochrome mode it is equivalent to DST .AND. 
SRC*. 

DST .OR. (ISRC). 

DST .AND. (ISRC). 

The SRC* pixels with a certain color are transparent 
meaning that the corresponding DST* pixels are 
seen through: 

For a monochrome device, the color is 

RGB MASK MONO, which is white. 

For a gray -scale devices, the color is 

RGB MASK GREY, which is white 

For a color device, the color is 

RGB MASK COLOR, which is magenta. 

The total number of raster operations 


* Where SRC is the source bitmap buffer, and DST is the destination bitmap buffer. 
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Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEERect 


Description: 


AEERect is used to define a rectangle used by various Display, Graphics, Text Control, 
and other helper functions. 


Definition: 
typedef structure 
( 
intl6 x, y; 
intl6 dx, dy; 
+ AFERect; 














Members: 


x The horizontal coordinate for the beginning (top left corner) of the rectangle. 
y The vertical coordinate for the beginning (top left corner) of the rectangle. 
dx The width of the rectangle (in pixels). 

dy The height of the rectangle (in pixels). 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEERingerCat 


Description: 
This data structure contains information about a ringer category. 


Definition: 
typedef structure | AEERingercat 
























































f 
AEERingerCat ID id; 
AEERingerID idRinger; 
AECHAR szName [MAX RINGER CATEGORY] ; 
+ AEERingercat; 
Members: 
id ID for the category for use in later calls. 
idRinger ID of default ringer for category. 
szName Wide string name of category. 
Comments: 
None 
See Also: 
AEERingerlD 


Return to the List of data structures 
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AEERingerCatID 


Description: 
Ringer category identifier. 


Definition: 
None 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEERingerEvent 


Description: 


AEERingerEvent specifies the different notifications sent by the IRingerMgr Interface. 
These are sent using the notification function registered using 
IRINGERMGR RegisterNotify(). 


Definition: 
typedef enum 

t 

ARE NONE, 
ARE PLAY, 
ARE CREATE, 
ARE WRITE 
+ AEERingerEvent; 


















































Members: 
ARE NONE No notification is sent. 
ARE PLAY Sent when play is done or when IRINGERMGR Stop() is 
called. 
ARE CREATE Sent when creation of the ringer is done or when an error 
occurs. 


ARE WRITE Sent any time the ringer file is written to. 


Comments: 
None 


See Also: 
PFNRINGEREVENT 
IRINGERMGR RegisterNotify() 
Return to the List of data structures 
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AEERingerlD 


Description: 
Ringer identifier. 


Definition: 
None 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEERingerlnfo 


Description: 
This data structure contains information about a ringer. 


Definition: 
typedef struct | AEERingerInfo 

















f 

AEERingerID id; 
AEESoundPlayerFile format; 
e 

A 

) 




















har szFile [MAX FILE NAME]; 
ECHAR szName [MAX RINGER NAME 
AEERingerInfo; 























Ls 
=. 

















Members: 
id ID of the ringer. 
format Sound format of the ringer. 
szFile[MAX FILE NAME] Full file path to the ringer file. O(zero) string, if read- 


only. 
szName[MAX RINGER NAME] Name of the ringer. 


Comments: 
None 


See Also: 
AEERingerlD 
AEESoundPlayerFile 
Return to the List of data structures 
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AEERLP3CIg 


Description: 


The network layer of some devices may use RLP3 under PPP, which might be able to 
be configured. This is the data structure that represents RLP3 configuration. Pass this 
struct as pOptVal to OEMNet SetRLP3Cfg(). 


Definition: 
typedef struct AEERLP3CÍg ( 
byte ucFwdNakRounds; 
byte aucFwdNaksPerRound [3]; 
byte ucRevNakRounds; 
byte aucRevNaksPerRound [3]; 
JAEERLP3CÊ9; 























Members: 
ucFwdNakRounds number forward NAK rounds (3 max) 
aucFwdNaksPerRound NAKs per round, forward 
ucRevNakRounds number reverse NAK rounds (3 max) 
aucRevNaksPerRound NAKs per round, reverse 
Comments: 


* The Maximum NAK count can be 3 in any round. If it's greater than 3, SetOpt 
returns AEE NET EBADOPTVAL 


* If NakRounds is less than 3, the RLP layer ignores the values in the 
NaksPerRound that correspond to those extra rounds. 


Example: 

ifucFwdNaksPerRound is setto 2, aucFwdNaksPerRound [2] is ignored 
* To set CUR RLP (current) option, the data connection must be active. 
* if NEG RLP values cannot be modified, SetOpt returns EBADPARM 


See Also: 
OEMNet SetRLP3Cfg() 
Return to the List of data structures 
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AEESectorinfo 














Description: 
This structure is used to obtain sector based position location information from the 
system. 
Definition: 
typedef struct  AEESectorInfo 
f 
uintl6 wSysID; 
uint16 wNet ID; 
uint16 wBaseID; 
uint1l6 wBaseClass; 
uint16 wBestPN; 
uint16 wBestPN; 
uint16 wPacketZoneID; 
uint16 wMobileCountryCode; 
JAEESectorInfo; 











Members: 
wSysID System Identification 
wNetID Network Identification 
wBaseStationlD Base Station Identification 
wBaseStationClass Base Station Class 
wBestPN Best Pilot 
wPacketZonelD Packet Data Service Zone Identifier 
wMobileCountryCode Mobile country code 

Comments: 
None 

See Also: 


IPOSDET GetSectorlnfo() 
Return to the List of data structures 
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AEESize 


Description: 
This structure specifies the size. 


Definition: 
typedef struct AFESize 
f 
int32 cx; 
int32 cy; 
) AEESize; 


























Members: 


Cx Width 
Cy Height 


Comments: 
None. 


See Also: 
None 
Return to the List of data structures 
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AEESMSMsg 


Description: 


This structure is given to the application as a dwParam parameter ofthe EVT NOTIFY 
event as part ofthe NMASK TAPI SMS TEXT orthe NMASK TAPI SMS TS 
notifications. The dwParam is of type AEENotify. The member pData contains the 
actual message. Pass this to ITAPI ExtractSMSText() to extract the formatted text. 


Definition: 
None 


Members: 
None 


Comments: 
None 


See Also: 
AEENotify 


Return to the List of data structures 
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AEESMS TextMsg 


Description: 


This structure is given to the application as a dwParam parameter ofthe EVT NOTIFY 
event as part ofthe NMASK TAPI SMS TEXT notification. The dwParam is of type 
AEENotify. The member pData contains the actual message. Pass this to 

ITAPI ExtractSMSText() to extract the formatted text. 


Definition: 
typedef struct 
f 
uint16 nChars; 
char szText [1]; 
+ AEESMSTextMsg; 














Members: 


nChars Number of characters. 
szText[1] Size of the Text 


Comments: 
None 


See Also: 
ITAPI ExtractSMSText() 
Return to the List of data structures 
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AEE SoundPlayerFile 


Description: 
AEESoundPlayerFile indicates the type of file being played. 


Definition: 
typedef enum 














EE SOUNDPLAYER FILE UNKNOWN, 
EE SOUNDPLAYER FILE MIDI, 

EE SOUNDPLAYER FILE MP3, 

EE SOUNDPLAYER FILE LAST 
AEESoundPlayerFile; 
























































-DpPppp- 














Members: 


AEE SOUNDPLAYER FILE UNKNOWN | Invalid type. 
AEE SOUNDPLAYER FILE MIDI MIDI. 

AEE SOUNDPLAYER FILE MP3 MPS. 

AEE SOUNDPLAYER FILE LAST Reserved. 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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AEE TextinputMode 


Description: 


This enumerated type specifies the text-entry modes that can be used to enter text into 
a text control. The function ITEXTCTL SetinputMode() is used to select the input 
mode that is used for a particular text control instance. 


Definition: 
typedef enum 





EE TM NONE 




















EE TM CURRI 
EE TM SYMBOLS, 


r 


ENT, 








EE TM LETT 
EE IM RAPI 
EE TM NUMB 























-DPpPpppDpD- 














Members: 
AEE TM NONE 


ERS, 
D, 





ERS 
ABEText InputMode; 


No input mode is currently specified.The default mode is 
AEE TM LETTERS. 


AEE TM CURRENT ' Designates the currently active input mode. 
AEE TM SYMBOLS Key presses enter the special symbol (if any) associated with 


AEE TM LETTERS 


AEE TM RAPID 


each key. 


Key presses enter the letter of the alphabet associated with 
each key. 


Rapid (T9) mode is to be used. 


AEE TM NUMBERS Key presses enter the number associated with each key. 


AEE TM MAX 
AEE TM USER 


AEE TM NUMBERS 
AEE TM MAX +1 


AEE TM FIRST OEM AEE TM USER, Oem added modes start at this value. 
AEE TM RESERVED 0x7000 and up are reserved for BREW 


Comments: 


The available text entry modes differ with each BREW-enabled device. 


See Also: 


ITEXTCTL SetlnputMode() 
Return to the List of data structures 
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AEE TextinputModelnfo 


Description: 
This structure contains the an AEE TextinputMode and a buffer to hold the string that is 
associated with that mode to be filled when using the ITEXTCTL GetlnputMode() 
function. 


Definition: 
typedef structure  AEEText InputModeInfo 
f 
AEEText InputMode tmMode; 
AECHAR modeString [MAX TEXT MODE SIZE]; 
+ AEEText InputModeInfo; 


















































Members: 


tmMode Text Mode enum entry. 
modesString String that is associated with the mode. 


Comments: 
The available text entry modes differ with each BREW-enabled device. 


See Also: 
ITEXTCTL GetinputMode() 
AEETextinputMode 
Return to the List of data structures 
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Description: 
This struct 


Definition 


typedef s 


int 
int 


Members: 
pMapArray 


unFlags 


reserved 


x 


unTileSize 


reserved2 


Data Types 


p 


describes a tile map. 


truct 1 

t16 *pMapArray; 
t32 unFlags; 

t32 reserved [4]; 
Ses 

32 yi 

L16 w; 

t16 h; 

t8 unTileSize; 
t8 reserved2 [3]; 
EETileMap; 














Array of tile indices and properties. This is a one-dimensional representation 
of the two-dimensional map. The rows of the map are unwrapped to make this 
one-dimensional array. (The first element of the second row follows the last 
element of the first row.) The bottom ten bits of each element are used for the 
index into the tile buffer. (TILE INDEX MASK masks these bits.) The special 
index value of TILE INDEX NOTHING means “don't draw a tile here.” The 
TILE FLIP , TILE ROTATE ,andTILE TRANSPARENT flags are applied to 
the elements of this array. The special value of pMapArray == NULL signifies 
that this is the last AEETileMap structure in the array passed to 

ISPRITE DrawTiles(). In this case, the other members of the AEE TileMap 
structure are ignored. 


Flags that apply to the entire tile map. Currently, only MAP FLAG WRAP is 
defined. 


Reserved for future use. Itis VERY important that these be set to zero. 


The screen x-coordinate where the upper left corner of the background will be 
drawn. 


The screen y-coordinate where the upper left corner of the background will be 
drawn. 


The width dimensions oftile map, specified in units of tiles. These are not the 
literal dimensions. Instead, the MAP SIZE values are used here. 


The height dimensions of tile map, specified in units of tiles. These are not the 
literal dimensions. Instead, the MAP SIZE values are used here. 


Size of the tiles. This is one of the TILE SIZE values. 


Reserved for future use. Itis VERY important that these be set to zero. 
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Comments: 
None 


See Also: 
ISPRITE DrawTiles(), 
Tile Properties 
Tile Map Properties 
Return to the List of data structures 
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AEE TransformMatrix 


Description: 
This struct describes a 2X2 matrix used for doing complex transformations. 














Definition: 
typedef struct ( 
intl6 A; 
intl6 B; 
intl6 C; 
int1l6 D; 
) AEETransformMatrix; 
Members: 


A,B,C, D: Fixed point values with and 8-bit integer part and an 8-bit fractional part. 
(For example, 2.5 would be represented as 2.5 * 256 or 640.) This makes up a 2x2 
matrix as follows 


[AB 
CDI] 


Comments: 
Some example transforms 
Scale by 2.5: A= 640, B=0, 
C=0,D = 640. 
Rotate: A = 256 * cos(angle), B = 256 * sin(angle), 
C = 256 * -sin(angle), D = 256 * cos(angle). 
Note: The above values have already been converted to fixed point. 


See Also: 
ITRANSFORM TransformBltComplex() 
Return to the List of data structures 
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AEEUDPUrgent 


Description: 


The physical layer of some devices may support various modes of data The physical 
layer of some devices may support various modes of data communication. This struct 
provides information about whether lower-latency communication is possible when 
PPP is asleep instead of waiting for complete wakeup in order to send a user 
datagram. 


Definition: 
typedef struct AEEUDPUrgent 
t 
boolean bUrgentSupported; 
uint1l6 nUrgentLimit; 
+ ABEUDPUrgent; 


























Members: 
bUrgentSupported TRUE if data may be deliverable while PPP is asleep, FALSE if 
not 
nUrgentLimit Maximum number of bytes of user data which may be sent per 
packet in this mode 
Comments: 


The flag and limit are only advisory. It may be that data will end up blocking for PPP 
wakeup anyway even if bUrgentSupported is TRUE. Similarly, the actual supported 
urgent payload limit may be smaller than offered, and can be context and environment 
dependent. 


See Also: 
OEMNet GetUrgent() 
Return to the List of data structures 
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Camera Command codes 


Description: 


Command code is returned via registered callback function to indicate event type and 
to return data to client. AEECameraStatus::nStatus in the GetStatus() function called 
from callback function contains the following command codes. 


Definition: 
CAM CMD BASE Base used by 
IMedia 
CAM CMD USER BASE Base for derived 
class 
CAM CMD SETPARM SetParm() nSubCmd = nParmlD 
CAM CMD GETPARM GetParm() nSubCmd = nParmlD 
CAM CMD START Start() nSubCmd = 


CAM MODE PREVIEW, 
CAM MODE SNAPSHOT, 
CAM MODE MOVIE 

CAM CMD ENCODESNAPSHOT EncodeSnapshot() 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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Camera Control Parameters 


Description: 
CAM PARM XXX 
These parameters (CAM PARM XXX) allow setting/getting the camera parameters. 
They are used in ICAMERA SetParm() and ICAMERA GetParm() APIs. 
Definition:CAM PARM MEDIA DATA 
Set: Sets the media data before encoding. This is done in Ready mode before calling 
ICAMERA RecordSnapshot() or ICAMERA RecordMovie() 
p1 = AEEMediaData * 
p2 = MIME string (NULL terminated) 
Get: Gets the current media data. 
p1 = AEEMediaData * 
p2 = Pointer to MIME string (const char **) 
Note: String p2 should be copied and should not be freed. 
CAM PARM VIDEO ENCODE 
CAM PARM AUDIO ENCODE 
Set: Sets the active video/audio encode type for encoding. This is done in Ready mode 
before calling ICAMERA RecordSnapshot() or ICAMERA RecordMovie() 
pf = CAM ENCODE XXX or AEECLSID of the media format 
p2 = Extra info regarding the encoding like sub formats. 
Get: Gets the current active encode type. 
p1 = Pointer to active encode type. 
p2 = Extra info regarding the encoding like sub formats. 
CAM PARM SIZE 
Set: Sets the size of the picture to be recorded. This is done in Ready mode before 
calling ICAMERA RecordSnapshot() or ICAMERA RecordMovie(). 
p1 = AEESize * 
Get: Gets the current picture size. 
p1 = AEESize * 
CAM PARM DISPLAY SIZE 
Set: Sets the frame display size for preview and movie modes. 
p1 = AEESize * 
Get: Gets the current frame display size. 
p1 = AEESize * 
CAM PARM DEFER ENCODE 


Set: This parm enables/disables deferring of the frame (snapshot) encoding done by 
ICAMERA RecordSnapshot() API. 


p1 = boolean. TRUE => Defer enabled. 
Get: Gets the current value 
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p1 = boolean * 
CAM PARM MODE 
Get: Gets the camera mode. 
p1 = Pointerto CAM MODE XXX 
p2 = Pointer to boolean: TRUE/FALSE: Paused/Resumed. 
CAM PARM IS SUPPORT 
Get: Checks if specified parm is supported. 
p1[in] = ParmlD 
p2[out] = Pointer to boolean: TRUE/FALSE => Supported/Unsupported. 
CAM PARM IS MOVIE 
Get: Checks if camera records movie. 
p1[out] = Pointer to boolean: TRUE/FALSE => Supported/Unsupported. 
CAM PARM PIXEL COUNT 
Get: Returns camera pixel count. 
p1[out] = AEE Size * 
CAM PARM VIDEO ENCODE LIST 
CAM PARM AUDIO ENCODE LIST 
Get: Returns list of supported video/audio encoding formats. 
Output: 
p1 = Pointer to NULL-terminated list of AEECLSID (AEECLSID **) 
Note: The list should be copied and should not be freed. 
CAM PARM SIZE LIST 


Get: Returns list of discrete sizes supported or continuos range (e.g. any size between 
10x10 to 100x150) for specified mode. 


Input: 


pf=CAM MODE SNAPSHOT/CAM MODE MOVIE (*ppList must contain 
this value) 


Output: 
p1 = Pointer to NULL-size terminated list of AEESize (ppList of type AEESize 
++) 
If NULL, indicates that any value is supported. 
p2 = Pointer to boolean, bRange, when TRUE indicates the passed list 
is a NULL-terminated paired list (i.e. multiple of 2) of ranges 
Note: The list should be copied and should not be freed. 
CAM PARM DISPLAY SIZE LIST 


Get: Returns list of discrete display sizes (typically for preview or movie mode) 
supported or continuos range (e.g. any size between 10x10 to 100x150) for specified 
mode. 


Input: 
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pf=CAM MODE PREVIEW/CAM MODE MOVIE (*ppList must contain this 
value) 


Output: 


p1 = Pointer to NULL-size terminated list of AEE Size (ppList of type AEESize 
**) If NULL, indicates that any value is supported. 


p2 = Pointer to boolean, bRange, when TRUE indicates the passed list is a 
NULL-terminated paired list (i.e. multiple of 2) of ranges 


Note: The list should be copied and should not be freed. 
CAM PARM FPS LIST 
Get: Returns list of supported discrete frames per second(FPS) or continuos range 
(e.g. any size between 5 to 30) for specified mode. 
Input: 


pf=CAM MODE PREVIEW/CAM MODE MOVIE (*ppList must contain this 
value) 


Output: 


p1 = Pointer to NULL-terminated list of uint32 dwFPS (ppList of type uint32 **). 
See dwFPS formatin CAM PARM FPS documentation. If NULL, indicates 
that any value is supported. 


p2 = Pointer to boolean, bRange, when TRUE indicates the passed list is a 
NULL-terminated paired list (i.e. multiple of 2) of ranges 


Note: The list should be copied and should not be freed. 
CAM PARM OVERLAY 


Set: Sets the overlay image that will be part of the recorded picture. This operation is 
done any camera mode. 


p1 = IBitmap * 
Note: You can add overlays on top of another image by calling this function repeatedly 
with different images. To clear ALL overlays, call this function with p1 = O, p2 = NULL. 


Get: Gets the current overlay info. 
p1 = IBitmap * 
CAM PARM GPSINFO 


Set: Sets AEEGPSInfo to be encoded in the image. This has to be set for each 
recording. 


p1 = AEEGPSInfo * 
CAM PARM EXIF IFDTAG 


Set: Set Exchangeable Image File Format (EXIF 2.2+) tags to be encoded in the 
image. This has to be set for each recording. 


p1 = CameraExifTaglnfo * 
CAM PARM QUALITY 


Set: Sets the quality of the picture to be recorded. This is done in Ready mode before 
calling ICAMERA RecordSnapshot() or ICAMERA RecordMovie(). 


p1 = int32 value 
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Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
CAM PARM FPS 


Set: Sets the frames per second of the camera preview and movie modes. This is done 
in Ready mode before calling ICAMERA Preview() or ICAMERA RecordMovie(). 


p1 = uint32 dwFPS value. dwFPS format: Lower 16 bits is Numerator. Upper 
16 bits is Denominator. Zero denominator is treated as 1. 


Get: Gets the current FPS. 
p1 = Pointer to FPS value 
CAM PARM CONTRAST 
Set: Sets the contrast of the picture to be recorded. This operation is done in any of the 
camera modes. 
p1 = int32 value 
Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
CAM PARM BRIGHTNESS 


Set: Sets the brightness of the picture to be recorded. This operation is done in any of 
the camera modes. 


p1 = int32 value 
Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
CAM PARM SHARPNESS 


Set: Sets the sharpness of the picture to be recorded. Sharpness, typically, specifies 
the number of adjacent pixels to be used, by camera sensor, to compose the each 
pixel. 


This operation is done in any of the camera modes. 
p1 = int32 value 
Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
CAM PARM ZOOM 


Set: Sets the zoom level of the picture to be recorded. This operation is done in any of 
the camera modes. 


p1 = int32 value 

Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
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CAM PARM ROTATE PREVIEW 


Set: Sets the rotation angle of the picture to be previewed. This operation is done only 
in preview modes. It affects preview mode only. 


p1 = int32 value 
Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
CAM PARM ROTATE ENCODE 


Set: Sets the rotation angle of the picture to be recorded and encoded. This operation 
is done in snapshot or movie mode. It affects snapshot/movie modes only. 


p1 = int32 value 
Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEEParminfo * 
CAM PARM EXPOSURE 


Info: Exposure is the amount of light on the subject. For example when recording a 
backlighted subject 


or a subject in snow, increase the exposure, and when recording a subject with 
extremely bright illumination such as spotlight, decrease the exposure. 


Following exposure modes are defined to automatically adjust the exposure based on 
the scene: 


CAM EXPOSURE AUTO: Auto setting 
CAM EXPOSURE DAY: For subjects under day light 
CAM EXPOSURE NIGHT: For subjects in dark environments 
CAM EXPOSURE LANDSCAPE: For distant subjects 
CAM EXPOSURE STRONG LIGHT: For subjects in strong or reflected light 
CAM EXPOSURE SPOTLIGHT: For subjects in spotlight 
CAM EXPOSURE PORTRAIT: For subjects behind an obstacle 
CAM EXPOSURE MOVING: For moving subjects 
Set: Sets the exposure. This operation is done in any of the camera modes. 
pf = CAM EXPOSURE XXX 
Get: Gets the current value. 
p1 = Pointer to current value 
CAM PARM WHITE BALANCE 


Info: White Balance adjustment is adjusting the perception of light by the camera. For 
example, the image looks blue under sunlight, and looks red under mercury lamps. 
Human eyes can resolve these problems but camera cannot resolve without making 
adjustments. 


Following white balance modes are supported. 
CAM WB AUTO: Auto 
CAM WB CUSTOM: Custom value provided by user 
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CAM WB INCANDESCENT: For subjects under incandescent lighting 
CAM WB TWILIGHT: For subjects under low light or dark conditions 
CAM WB FLUORESCENT: For subjects under fluorescent lighting 


CAM WB DAYLIGHT: For subjects under sunlight, strong or varying light 
conditions or under sodium/mercury lamps 


CAM WB CLOUDY DAYLIGHT: For subjects under cloudy daylight 
conditions 


CAM WB SHADE: For subjects under shade 
Set: Sets the white balance. This operation is done in any of the camera modes. 
pf=CAM WB XXX 
Get: Gets the current value. 
Input: 
p1f=CAM WB CUSTOM or any 
Output: 
p1 = Pointer to current value 
p2 = AEEParminfo *, if p1 (as input) is CAM WB CUSTOM 
CAM PARM EFFECT 
Info: Effect parameter allows you process the image to obtain special effects. 
Following effect types are defined: 
CAM EFFECT OFF: No special effect 
CAM EFFECT MONO: Black and white 
CAM EFFECT NEGATIVE: Color and brightness reversed 
CAM EFFECT SOLARIZE: Light intensity emphasized 
CAM EFFECT PASTEL: Contrast emphasized 
CAM EFFECT MOSAIC: Mosaic 
CAM EFFECT RESIZE: Stretch along x or y. Aspect ratio not preserved. 
CAM EFFECT SEPIA: Sepia effect 
Set: Sets the camera effect mode. 
This operation is done in any of the camera modes. 
pf=CAM EFFECT XXX 
p2 = Destination AEE Size *, if pf is CAM EFFECT RESIZE 
Get: Gets the current value. 
p1 = Pointer to current value 
p2 = AEESize *, if pf is CAM EFFECT RESIZE 
CAM PARM FLASH 
Info: Allows flash control. Following flash control options are supported: 
CAM FLASH AUTO: Auto 
CAM FLASH OFF: Off 
CAM FLASH LOW: Low intensity 
CAM FLASH MEDIUM: Medium intensity 
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CAM FLASH HIGH: High intensity 
CAM FLASH CUSTOM: Custom value provided by user 
Set: Sets the flash control mode. This operation is done in any of the camera modes. 
pf=CAM FLASH XXX 
p2 = uint32 value for CAM FLASH CUSTOM 
Get: Gets the current value. 
Input: 
pf=CAM FLASH CUSTOM or any 
Output: 
p1 = Pointer to current value 
p2 = AEEParminfo *, if p1 (as input) is CAM FLASH CUSTOM 
CAM PARM RED EYE REDUCTION 
Info: Enables/Disables red-eye reduction capability. 
Set: Sets red-eye enable/disable parameter 
p1 = boolean: TRUE/FALSE => Enable/Disable 
Get: Gets the current value. 
Input: 
p1 = boolean * 


Members: 
None 


Comments: 
None 


See Also: 
Return to the List of data structures 
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Camera Status codes 


Description: 


Data Types 


Status code is returned via registered callback function to indicate event status and to 
return data to client. AEECameraStatus::nStatus sent via callback function contains the 


following status codes. 


Definition: 


CAM STATUS BASE 
CAM STATUS USER BASE 


CAM STATUS START 


CAM STATUS DONE 


CAM STATUS FAIL 


CAM STATUS ABORT 


CAM STATUS FRAME 

CAM STATUS PAUSE 

CAM STATUS RESUME 

CAM STATUS DATA IO DELAY 


CAM STATUS SPACE WARNING 


Members: 
None 


Comments: 
None 


See Also: 
Return to the List of data structures 


Base used by ICamera 
Base for extension 


[Preview, Record] Operation started 
successfully 

[Preview, Record, SetParm, GetParm, 
EncodeSnapshot] Operation completed 
successfully 

For RecordSnapShot, pData = TRUE/FALSE => 
Defered encode enabled/disabled 

[Preview, Record, SetParm, GetParm, 
EncodeSnapshot] Operation failed, pData = 
CAM EXXX error code. 


[Any] Current operation aborted: Camera 
entered ready state 


[Any] Frame captured by camera. 
[Preview, Record] Record movie paused 
[Preview, Record] Record movie resumed. 


[Preview, Record] Operation being delayed by 
data i/o access 


[Record] Memory available to store recording 
running low 
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CameraExifTaglnfo 


Description: 


This structure specifies Exchangeable Image File Format (EXIF 2.2+) tag info to be 
encoded in the image. 


Definition: 
typedef struct CameraExifTagInfo 

f 
uintl6 wTagID; 
uintl6 wTagType; 
void * pTagData; 
uint32 dwBytes; 
uintl6 wIEDID; 
uintl6 wReserved; 
) CameraExifTagInfo; 











Members: 


wTaglD [Mandatory] TaglD 

wTagType [Mandatory] Tag data type 

pTagData [Mandatory] Tag data 

dwBytes [Mandatory] Number of bytes in pTagData 
wIFDID [Optional] IFD ID. Use Default for most cases 
wReserved Reserved 


Comments: 
None. 


See Also: 
ICAMERA SetParm() 
Return to the List of data structures 
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CMediaFormat 


Description: 
This structure contains the common data members for all IMedia-based objects. 
It is derived from AEEMedia structure. 


Definition: 
OBJECT(CMediaFormat) 
t 
INHERIT CMediaFormat(IMediaMIDI); 
; 


Members: 


INHERIT CMediaFormat(IMediaMID!): Inherits members from AEEMedia and 
contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia 
Return to the List of data structures 
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CMediaMIDI 


Description: 


This structure contains the data members for IMediaMIDI interface 
implementation. 


Definition: 
OBJECT (CMediaMIDI) 
( 


INHERIT CMediaFormat (IMediaMIDI); 
+; 








Members: 


INHERIT CMediaFormat(IMediaMID!): Inherits members from AEEMedia and 
contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia structure, CMediaFormat structure. 
Return to the List of data structures 
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CMediaMIDIOutMsg 


Description: 
This structure contains the data members for IMediaMIDIOutMsg interface 
implementation. 


Definition: 
OBJECT(CMediaMIDIOutMsg) 
t 
INHERIT CMediaFormat(IMediaMIDIOutMsg); 
); 


Members: 


INHERIT CMediaFormat(IMediaMIDIOutMsg): Inherits members from AEEMedia and 
contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia structure, CMediaFormat structure. 
Return to the List of data structures 
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CMediaMIDIOutQCP 


Description: 
This structure contains the data members for IMediaMIDIOUtQCP interface 
implementation. 


Definition: 
OBJECT(CMediaMIDIOUtQCP) 
f 
INHERIT CMediaFormat(IMediaMIDIOUtQCP); 
x; 


Members: 


INHERIT CMediaFormat(IMediaMIDIOUtQCP): Inherits members from AEEMedia 
and contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia structure, CMediaFormat structure. 
Return to the List of data structures 
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CMediaMP3 


Description: 
This structure contains the data members for IMediaMP3 interface 
implementation. 


Definition: 
OBJECT(CMediaMP3) 
t 
INHERIT CMediaFormat(IMediaMP3); 
); 


Members: 


INHERIT CMediaFormat(IMediaMP3): Inherits members from AEEMedia and 
contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia structure, CMediaFormat structure 
Return to the List of data structures 
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CMediaPMD 


Description: 
This structure contains the data members for IMediaPMD interface 
implementation. 


Definition: 
OBJECT(CMediaPMD) 
t 
INHERIT CMediaFormat(IMediaPMD); 
>; 


Members: 


INHERIT CMediaFormat(IMediaPMD): Inherits members from AEEMedia and 
contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia structure, CMediaFormat structure. 
Return to the List of data structures 
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CMediaQCP 


Description: 
This structure contains the data members for IMediaQCP interface 
implementation. 


Definition: 
OBJECT(CMediaQCP) 
t 
INHERIT CMediaFormat(IMediaQCP); 
); 


Members: 


INHERIT CMediaFormat(IMediaQCP): Inherits members from AEEMedia and 
contains 


pointer to CMediaMMLayer. 


Comments: 
None 


See Also: 
AEEMedia structure, CMediaFormat structure. 
Return to the List of data structures 
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Configuation Parameters 


Description: 


Following are the values for the configuration parameters used in OEM GetConfig() and 
OEM SetConfig() 


Definition: 
CFGI DNS IP1 
32-bit main Domain Name Server (DNS) IP Addresss in network byte-order 
CFGI DNS IP2 
32-bit backup Domain Name Server (DNS) IP Address in network byte-order 
CFGI DOWNLOAD 
information pertinent to the download service with the following information: 
+ dwCarrierlD: 32-bit carrier ID 
+ dwPlatformlD: 32-bit handset platform ID 
+ bBKey: string of OEM programmed B-Key or all zeros 
+ bAKey: string of SSD A derived from A-Key or all zeros 
+ szServer: string of server name 


+ wFlags: 16-bit download related flags which can have one or more of the following 
values set: 


*DIF USE A KEY: if set, use A-Key; otherwise use B-Key 

*DIF TEST ALLOWED: if set, the handset can be used to test local apps 

*DIF MIN FOR SID: if set, use the MIN for the SID 

* DIF PREPAY: if set, itis a prepay phone 

* DIF EULA: if set, check for End-User-License-Agreement 

*DIF NO AUTO ACK: if set, do not force ACKs until user runs MobileShop 
*DIF SID VALIDATE ALL if set, validates all apps rather than just SSN apps 


*DIF RUIM DEL OVERRIDE if set, allows one RUIM user to delete apps owned by 


another 
+ nAuth: download authentication policy which can be one of the following values: 
* APOLICY NONE: No authentication required 


* APOLICY SID: User's "subscriber ID" is passed to ADS before any set of 
transactions started 


* APOLICY TEXT: User should be prompted for text "key" and this sent to ADS 


* APOLICY NUM- User should be prompted for numeric "key" and this sent to ADS 
+ nPolicy: privacy policy which determines the type of certification required to run applet 


on the handset: 
* PPOLICY BREW: TRUE-BREW-signed applet only 
* PPOLICY CARRIER: carrier-signed applet only 
* PPOLICY BREW AND CARRIER: TRUE-BREW- and carrier-signed applet only 
* PPOLICY BREW OR CARRIER: TRUE-BREW- or carrier-signed applet 
CFGI SUBSCRIBERID 
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32-byte subscriber ID in ASCII 
CFGI MOBILEINFO 
information about the handset which include the following: 
+ nCurrNAM: 8-bit handset's NAM 
+ dWESN: 32-bit handset's ESN 
+ szMobilelD: 16-byte mobile number which consists of the following components: 
* mec: 3-digit mobile coutry code 
* mnc: 2-digit mobile network code 
* min2: 3-digit mobile area code 
* min1: 7-digit mobile phone number 
CFGI AUTOSTART 
class ID of the applet to be auto-started when AEE is initialized through AEE Init(). 
CFGI BUSY CURSOR OFFSET 
offset position of the hourglass from the center of the screen. Itis of the type AEERect 
which has the following fields: 
+ x: x-offset from the center of the screen 
+ y: y-offset from the center of the screen 
+ dx: ignored 
+ dy: ignored 
CFGI DOWNLOAD BUFFER 
32-bit unsigned integer value for the download buffer size, in bytes. The default is 10 
kilobytes. 
CFGI HTTP BUFFER 
32-bit unsigned integer value for the HTTP read buffer size, in bytes. The default is 4 
kilobytes. 
CFGI NET CONNTIMEOUT 
32-bit unsigned integer value for the network connection timeout, in milliseconds. The 
default is 30 seconds. 
CFGI SUBSCRIBERID LEN 
32-bit signed integer value for size in bytes of subscriber ID The default length is 32. 
CFGI MAX DISPATCH TIME 
32-bit unsigned integer value for the maximum time BREW should spend in the dispatcher 
before relinquishing control. The default is 250 msecs. 
CFGI MIN IDLE TIME 
32-bit unsigned integer value for the minimum time BREW must relinquish from dispatcher. 
The default is 35 msecs. 
CFGI SLEEP TIMER RESOLUTION 
32-bit unsigned integer value for timer resolution during when processor/os is in SLEEP 
mode. The default is 1.2 seconds. 
CFGI SYSMEM SIZE 
32-bit unsigned integer value for size in bytes reserved to the system in low-memory. The 
default is 2K bytes. 
CFGI DOWNLOAD FS INFO 
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Available FS size for use and total FS size. (Fill dwFSAvail, dwFSSize in DLItemSize *) 
CFGI SCREEN SAVER 
AEEScreenSaverlnfo * 
CFGI DISALLOW DORMANCY 
boolean, if TRUE, disallow dormancy, 
CFGI DORMANCY NO SOCKETS 
boolean, whether to hold PPP (go dormant) even if no sockets are open 
CFGI CLOSE KEYS 
Information about the close keys which include the following 
+ wCloseApp: Virtual key of AVKType to close current app. The defaultis AVK CLR. 
+ evtCloseApp: AEEEvent 
EVT KEY PRESS, 
EVT KEY RELEASE, 
EVT KEY or 
EVT KEY HELD. 
The default is EVT KEY 
+ wCloseAIIApps: Virtual key of AVKType to close all apps. The defaultis AVK END. 
+ evtCloseAIIApps: AEEEvent 
EVT KEY PRESS, 
EVT KEY RELEASE, 
EVT KEY or 
EVT KEY HELD. 
The defaultis EVT KEY 
CFGI FILE CACHE INFO 
Information about the file cache info which include the following 


+ nCacheDefault: 32 bit signed integer value for the default cache size. The default is 
4K bytes. 


+ nCacheMin: 32 bit signed integer value for the minimum cache size. The default is 512 
bytes. 
+ nCacheMax: 32 bit signed integer value for the maximum cache size. 
The default is 10K bytes. 
CFGI MODULE FSLIMIT 
MIFFSLimit * (wMaxFiles and dwMaxSpace for the module) 
CFGI DATA NETWORK, 
OEM NET DEFAULT - Default data network 
OEM NET DOWNLOAD - Download data network 
OEM NET DATA - Normal data connections 


These values are passed to the OEM to allow them to switch data network parameters 
without revealing those parameters to the caller. 


CFGI CARDID LEN 
32-bit signed integer value for size in bytes of CFGI CARDID 
CFGI CARDID 
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byte * of size returned by CFGI CARDID LEN 
CFGI DEBUG KEY 
OEMDebugkKey * below 
CFGI DEBUG KEY 
This denotes the key sequence that BREW shall use for diagnostics information. The 
structure OEMDebugkKey must be filled. 
Here is the description of this structure: 


typedef struct 
t 
AVKType Key; 
int1l6 nRepeat; 
+ OEMDebugkey; 
key: The key to use for debug. By Default, its AVK POUND 


nRepeat: The number of times the above key must be pressed for BREW to enter into 
the debug mode. By default, this is set to 3 


BREW has a pre-defined set of debug commands. These are: 





DBG MEM KEY AVK 1 Checks pointers, run on new stack 

DBG NET KEY AVK 2 Prints Network diagnostics information on 
the screen 

DBG MEM AVAIL KEY AVK 3 Displays memory available 

DBG PRIV KEY AVK 4 Throws exception on priv violation 

DBG MALLOC KEY AVK 5 Throws exception on malloc failure 


DBG MALLOC TEST KEY AVK 6 | Failsevery Nmallocs (ex: 100 Mallocs) 


DBG DBGPRINTF KEY AVK 7 Toggle "synchronous" dbgprintf. Toggles 
between making dbgprintf synchronous or 


asynchronous 
DBG DUMP MODULES AVK 8 Not Supported 
DBG DUMP HEAP AVK 9 Dumps the heap 
DBG RESET KEY AVK 0 Resets (disables) all of the debug 


operations described above 


CFGI PROVISION FIRST=0x1000 

Offset to build dependent items 
CFGI PROVISION LAST=0x2000 

End of build dependent items 
CFGI MAX 

Holds max AEE value, not a function. 
CFGI FIRST OEM=CFGI MAX 

OEM added config items should start at this value. 
CFGI HTTP BUFFER 

Size in bytes of HTTP read buffer (default 4K) 
CFGI MAX DISPATCH TIME 


Maximum time BREW should spend in the dispatcher before relinquishing control (default 
= 250 msecs) 
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CFGI NET CONNTIMEOUT 
time in milliseconds! to wait for connect() 
CFGI ALLOW 3GTO2G FAILOVER 


boolean value that allows the 3G to 2G fail over to take place. By default it is not allowed. 


Members: 
None 


Comments: 
None 


See Also: 
OEM GetConfig() 
OEM SetConfig() 
Return to the List of data structures 
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CtlAddltem 


Description: 
An encapsulation for a control item added to the control. 


Definition: 
typedef structure  CtlAddItem 

t 
const AECHAR * pText; 
Ilmage * pImage; 
const char * pszResImage; 
const char * pszResText; 
uintl6 wText; 
uintl6 wFont; 
uint1l6 wImage; 
uint16 wItemID; 
uint32 dwData; 
) CtlAddItem; 





Members: 
pText Text in the item. 
plmage Image in the item. 
pszReslmage Name of the resource file. 
pszResText Name of the resource file. 
wText Resource ID of the text string. 
wFont O (zero). The default. 
wlmage Resource ID of the Image. 
wltemlD Control item ID. 
dwData Data value associated with menu item. 
Comments: 


pText and plmage are used by default. If they are not set (NULL), the pszReslmage 
and pszResText are used with wText and wlmage to load the text or image, 
respectively. 


See Also: 
None 
Return to the List of data structures 
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CtiValChange 


Description: 
This data structure is passed as dwParam along with the event 
EVT CTL CHANGING. This event is sent to the application when a specific control is 
changing. This allows the application to re-draw any portions of the screen. 


Definition: 
typedef struct | CtlValChange 
f 
IControl * pc; 
uint32 dwParam; 
boolean bValid; 
+ CtlValChange; 





Members: 
pc Pointer to the control that is changing 
dwParam This is control-specific data. In the case of the ITimeCtlI Interface, this specifies 
the current time in milliseconds 
bValid Parameter that can be set by the application on returmning from this event. If 
bValid is set to FALSE by the app, the control will not be re-drawn based on 
the new value 
Comments: 


This event is sent by specific controls only. For ex:TimeCtl. See the specific controls 
for more information on this event 


See Also: 
None 
Return to the List of data structures 
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FileAttrib 


Description: 
FileAttrib specifies the type of a file. 


Definition: 
typedef enum 

f 
“FA NORMAL-O, 
“FA HIDDEN-0x0001, 
“FA DIR=0x0002, 
“FA READONLY-0x0004, 
“FA SYSTEM-0x0008 
) FileAttrib; 








Members: 
“FA NORMAL File is normal file. 
“FA HIDDEN File is a hidden file (reserved). 
“FA DIR File is directory (reserved). 
“FA READONLY File is read only file. 
“FA SYSTEM File is system file. 
Comments: 
None 
See Also: 
None 


Return to the List of data structures 
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brew. 
Filelnfo 
Description: 
FileInfo is used to contain information associated with a file. 
Definition: 
typedef structure FileInfo 
f 
FileAttril attrib; 
uint32 dwCreationDate; 
uint32 dwSize; 
char szName [MAX FILE NAME]; 
) FileTInfo; 
Members: 
attrib File attributes specified by FileAttrib. 
dwCreationDate File creation date. Elapsed time in seconds since January 6, 1980 
00:00:00 GMT. 
dwSize File size. 
szName File name. 
Comments: 
None 
See Also: 
FileAttrib 


Return to the List of data structures 
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GSMSMSEncodingType 


Description: 


GSMSMSEncodingType defines the GSM message encoding, 7bit, 8bit, or unicode 
(UCS2). 


Definition: 
typedef byte GSMSMSEncodingType; 
GSMSMS. ENCODING YBIT 
GSMSMS. ENCODING 8BIT 
GSMSMS ENCODING UCS2 











Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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GSMSMSMsg 


Description: 


GSMSMSMsg contains a decoded GSM message. The msgType field determines 
which element of the union to use. See GSMSMSMsgType for a description of the valid 
values for msgType. 


Definition: 
typedef struct 

f 

GSMSMSMsgType msgType; 

union ( 
GSMSMSSubmit Type SMSSubmit; 
GSMSMSDeliverType SMSDeliver; 
GSMSMSSubmitReportType SMSSubmitReport; 
GSMSMSDeliverReportType SMSDeliverReport; 
GSMSMSStatusReportType SMSStatusReport; 
| msg; 

+ GSMSMSMsg; 





Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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GSMSMSMsgType 


Description: 


GSMSMSMsgType indicates the message type class ina GSMSMSMsg. This is used 
to determine which field of the GSMSMSMsg union to use. 


Definition: 
typedef byte GSMSMSMsgType; 
GSMSMS MSG SMS SUBMIT 
GSMSMS MSG SMS SUBMIT REPOR] 
GSMSMS MSG SMS DELIVER 
GSMSMS MSG SMS DELIVER REPORT 
GSMSMS MSG SMS STATUS REPOR 
GSMSMS MSG SMS COMMAND 
GSMSMS MSG SMS UNKNOWN 

















» 


























Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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GSMSMSRawMsg 


Description: 


GSMSMSRawMsg uses 2 raw message formats. The format field is set to either of the 
following: 


GSMSMS RAW FORMAT GSM for incoming messages, or 
GSMSMS RAW FORMAT SIM for messages retrieved from the SIM. 


The format is based on the setting of the format field and the appropriate union element 
is used. 


Definition: 
typedef struct ( 

GSMSMSRawFormat format; 
union ( 
GSMSMSRawData gsm; 
GSMSMSSIMData sim; 
+ msg; 
+ GSMSMSRawMsg; 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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GSMSMSStatus Type 


Description: 


GSMSMSStatusType indicates the status byte value of the GSM message stored in 
a particulat slot in the SIM. 


Definition: 


typedef byte GSMSMSStatusl 


GSMSMS. S 
GSMSMS. S 
GSMSMS. S 
GSMSMS. S 
GSMSMS. S 
GSMSMS. S 
GSMSMS. S 
GSMSMS. S 


Members: 
None 


Comments: 
None 


See Also: 
None 


Return to the List of data structures 






































ECE 






































— STORE 
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GSMSMSStorageType 


Description: 


GSMSMSStorageType indicates the desired message store: NVRAM, Voicemail 
(NVRAM VM), or the SIM. 


Definition: 
typedef byte GSMSMSStorageType; 
GSMSMS STORE NVRAM 
GSMSMS STORE NVRAM VM 
GSMSMS. STORE SIM 

















Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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I3D Events 


3D events are returned via registered event notify callback functions to indicate 3D 
rendering state and to return data to the client. 


Based off event type the user will know when it is okay to update the display. 


AEE3DEventNotify::EventType sent via notify callback function contains the following 
event types. 


fdefine AEESD EVENT FRAME STARTED 0x1 
fdefine AEESD EVENT FRAME COMPLETED 0x2 
fdefine AEESD EVENT FRAME UPDATE DISPLAY 0x3 
fdefine AEESD EVENT FRAME ERROR 0x4 


AEESD EVENT FRAME STARTED 


This event will indicate that processing and rendering for the current frame has started. 


AEESD EVENT FRAME COMPLETED 


This event will indicate that the current frame has completed the rendering process and 
itis okay to start working on that next frame. 


AEESD EVENT FRAME UPDATE DISPLAY 


This event will indicate that the current frame is now ready to display. Call 
UpdateDisplayEX() now. You may wish to modify the final ftame buffer before you call 
update display. For example, you could add overlaying 2D text then call 
UpdateDisplayEX(). 


AEESD EVENT FRAME ERROR 


This event will indicate that the frame had an error when rendering. The error code will 
be placed in the ErrorCode field of the AEE3DNotifyEvent. 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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IDC COMMAND RESERVED 


Description: 
This is a placeholder to indicate that all command IDs above this are reserved for 
internal BREW use 

Definition: 
fdefine IDC COMMAND RESERVED (0xff00) 

















Members: 
None 


Comments: 
This is used in conjunction with the EVT COMMAND sent by controls 


See Also: 
EVT COMMAND 
Return to the List of data structures 
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IDIB 


Description: 
This structure defines the BREW device-independent bitmap format. 


Definition: 
OBJECT (IDIB) | 
ABEVTBL (IDIB) *pvt; 
IQueryInterface * pPaletteMap; 
byte * pBmp; 
uint32 * pRGB; 
NativeColor ncTransparent; 
uintl6 cx; 
uintl6 cy; 
int16 nPitch; 
uint1l6 cntRGB; 
uint8 nDepth; 
uint8 nColorScheme ; 
uintê reserved[6]; 


) 

















Members: 


pvt Pointer to the v-table. Users should not access this directly; macros 
are provided for all the member functions (IDIB AddRef(), 
IDIB Release(), and IDIB QuerylInterface()). 

pPaletteMap Cache for computed palette mapping data.Generally, developers 
can ignore this field. This member provided for graphics operations 
that read from or write to the DIB. Some algorithms, like optimized 
DIB to native blits, involve complicated initialization steps that 
transform palette data to a more readily accessible foramt. Such an 
algorithm can store the initialization data in pPaletteMap to avoid the 
need for recomputing the next time it runs. Anyone replacing a non- 
NULL pointer must release the pre-existing pointer (with 
IQI Release()), and when the DIB is deleted any non-NULL pointer 


is released. 
pBmp Pointer to the top row of the pixel array. 
pRGB Pointer to the color palette. The color palette is an array of 32-bit 


color values. The size of the palette array is given in the cntRGB 
member. A palette defines the meaning of pixel values in the bitmap 
data. A pixel value of N corresponds to the color at index N in the 
palette. Any pixel value greater than the size of the palette is 
undefined. Palette color values are not RGBVAL values. Palette 
values are specified in terms of memory layout. The first byte is blue, 
the second byte is green, the third bute is red, and the fourth byte is 
ignored. On a little-endian processor, a palette value is the same as 
NTOHL(rgb). On a big-endian processor, it is compatible with 
RGBVAL. 
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ncTransparent 


CX 


Cy 
nPitch 
ecntRGB 


nDepth 
nColorScheme 


values 


reserved 


Comments: 
R-G-B intensity values correlate with actual perceived color, but the precise 


See Also: 


NativeColor 


Data Types 


Transparent color for the DIB. Note that this is notin RGB form; itis 
specified as a NativeColor, which corresponds directly to values in 
the pixel array. 

Width of bitmap in pixels. Reading or writing pixels at or above this 
indexn must be avoided. 

Height of bitmap in pixels. Reading or writing pixels at or above this 
index must be avoided. 

Offset from any row to the row below it. 

Number of entries in the palette. If this is zero, the bitmap contains 
no palette. If this is non-zero, then pRGB points to an array of palette 
entries. 

Size of each pixel, in bits. 

If non-zero, describes mapping from pixel values to R-G-B values. 
The following currently defined values for nColorScheme describe 
how bit fields within each pixel value represent red, green, and blue 
intenstiy 
The following values are color schemes: 

IDIB COLORSCHEME 332 

3 bits red, 3 bits green, 2 bits blue 
IDIB COLORSCHEME 444 

4 red, 4 green, 4 blue 
IDIB COLORSCHEME 555 

5 red, 5 green, 5 blue 
IDIB COLORSCHEME 565 

5 red, 6 green, 5 blue 

IDIB COLORSCHEME 888: 

8 red, 8 green, 8 blue 

In each case, the blue bits occupy the least significant bits of the pixel 
value, the green bits the next most significant, and then the red bits. 
Any leftover most significant bits are unused. 

Reserved bytes for future version. Initialize these bits to zeros when 
constructing a DIB; ingnore the value when parsing a DIB. 


relationship is complex and dependent upon the display hardware. IBitmap and IDIB 
are unconcerned with such issues. 


IBitmap Interface, List of functions 
IDIB Querylnterface() 

IDIB TO IBITMAP() 

Return to the List of data structures 
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INAddr 


Description: 
The parts of an internet IP endpoint, address and port. INAddr and INPort denote 
network byte-order values for the IP address and port of an IP socket or endpoint. 
Definition: 
typedef uint32 INAddr; 


Members: 
None 


Comments: 
None 


See Also: 
OEMNet MylIPAddr() 
INPort 
Return to the List of data structures 
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INPort 


Description: 
The parts of an internet IP endpoint, address and port. INAddr and INPort denote 
network byte-order values for the IP address and port of an IP socket or endpoint. 
Definition: 
typedef uint16 INPort; 


Members: 
None 


Comments: 
None 


See Also: 
INAddr 
Return to the List of data structures 
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ITransform Properties 


Description: 
These properties are used for various paramters of Transform functions. 


Definition: 

Flags for unTransform parameter of ITRANSFORM TransformBltSimple 
TRANSFORM FLIP X Flip over x axis. 
TRANSFORM ROTATE 90 Rotate 90 degrees counter-clockwise. 
TRANSFORM ROTATE 180 Rotate 180 degrees counter-clockwise. 
TRANSFORM ROTATE 270 Rotate 270 degrees counter-clockwise. 
TRANSFORM SCALE 2 Scale by a factor of 2. 
TRANSFORM SCALE 4 Scale by a factor of 4. 
TRANSFORM SCALE 8 Scale by a factor of 8. 
TRANSFORM SCALE EIGHTH Scale by a factor of 1/8. 
TRANSFORM SCALE QUARTER Scale by a factor of 1/4. 
TRANSFORM SCALE HALF Scale by a factor of 1/2. 


Values for unComposite parameter of ITRANSFORM TransformBltSimple and 
ITRANSFORM TransformBltComplex 


COMPOSITE KEYCOLOR Do transparent blit. This means that pixels that the 
transparency color of the source bitmap will not be drawn. 


COMPOSITE OPAQUE Do no (opaque) blit. 


Members: 
None 


Comments: 
Note: All transformation use the source bitmap's center as the origin. 


See Also: 
ITRANSFORM TransformBltComplex() 
ITRANSFORM TransformBlitSimple() 
IBITMAP SetTransparencyColor() 
Return to the List of data structures 
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NativeColor 


Description: 


The NativeColor type is used to represent the value of a single pixel in the bitmap. The 
interpretation of this value as a color is dependent of the format of the bitmap. You 
should not rely on this being in a particular format. Instead, you should use 

IBITMAP NativeToRGB() and IBITMAP RGBToNative() to access a NativeColor. 


Definition: 
typedef uint32 NativeColor; 


Comments: 
None. 


See Also: 
IBITMAP RGBToNative() 
IBITMAP NativeToRGB() 
Return to the List of data structures 
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NetSocket 


Description: 
NetSocket is an enumeration of the types of sockets that can be created with INetMgr 
Interface. 

Definition: 


typedef enum (AEE SOCK STREAM=0, AEE SOCK DGRAM) NetSocket; 


























Members: 


AEE SOCK STREAM TCP: streaming socket. 
AEE SOCK DGRAM UDP: datagram socket . 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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NetState 


Description: 


Data Types 


NetState is an enumeration of the states of the device's PPP connection to the Internet. 
A NetState value is returned by the OEMNet PPPsState() call. 


Definition: 
typedef enum ( 


NET INVALID STATE, 


ET PPP OPEN, 




















ET PPP AS 














—2zazgaaszga 


NetState; 


Members: 
NET INVALID STATE 


NET PPP OPENING 
NET PPP OPEN 
NET PPP CLOSING 
NET PPP CLOSED 
NET PPP SLEEPING 


NET PPP ASLEEP 


NET PPP WAKING 


Comments: 
None 


See Also: 
OEMNet PPPState() 





ET PPP OPENING, 


ET PPP CLOSING, 
ET PPP CLOSED, 
ET PPP SLEEPING, 
EEP, 
ET PPP WAKING, 


Not an actual state; this value is not returned by 
INETMGR NetStatus(). 


The PPP connection is being established. 

The PPP connection is active. 

The PPP connection is closing. 

The PPP connection is inactive. 

The PPP connection is "up", but non-PPP related network 
resources (e.g. CDMA traffic channel) are being released 
The PPP connection is "up", but non-PPP related network 
resources have been released 

The PPP connection is "up", and non-PPP related network 
resources are being re-acquired 


Return to the List of data structures 
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OEMAppEvent 


Description: 
This structure contains all of the elements of the event passed to the app. 
NOTE: No OEM modification of the parameters is supported. 


The app context of the target application has been asserted when this notification is 
made. Any calls to BREW will appear to come from the application. Moreover, access 
to system functions is limited based upon the rights of the app. 


Definition: 
typedef struct | OEMAppEvent 

f 
AEECLSID cls, 
ArEEvent evt: 
uint16 wp: 
uint32 dwp: 

+ OEMAppEvent; 












































Members: 


cls ClassiD of the app to which the event is being sent. 
evt Event Code of the event being sent to the app 

Wwp wParam of the event being sent to the app 

dwp dwParam of the event being sent to the app. 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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oemLogType 


Description: 


This structure type is defined in either log.h or log dmss.h depending on the target 
handset. This memberwill contain the standard DMSS log header (which 


contains the log code, length, and a timestamp), a standard brew header, and the log 
data send bythe BREW application. 
Definition: 


typedef logBinType oemLogType; 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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PFNCBCANCEL 


Description: 
This data structure specifies the prototype of the Cancel Function that can be used to 
cancel a callback 

Definition: 


typedef void (*PFEFNCBCANCEL) (AEECallback * pcb); 

















Members: 


pcb Pointer to the AEECallback that must be cancelled using this function 


Comments: 
This is used in conjunction with AEECallback 


See Also: 
AEECallback 
Return to the List of data structures 
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Description: 
Calback Function that is invoked when the EULA text is obtained from the server 
Definition: 
typedef void (*PFENDLTEXT) (void * pcext, int nErr, const AECHAR * 
pszText); 
Members: 
pext User Data passed when registering thic callback function( using 
IDOWNLOAD GetEULA()) 
nErr Error code (if any) in obtaining the EULA text. If successful, it returns 
AEE SUCCESS. if failed, it could return one of the following Errors 
EFAILED 
ENOMEMORY 
EUNSUPPORTED 
Comments: 
None 
See Also: 


IDOWNLOAD GetEULA() 
Return to the List of data structures 
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PFNMEDIANOTIFY 


Description: 


PFNMEDIANOTIFY is the type specification for callback function that user must 
register with the IMedia object. IMedia object sends all the events and data to user via 
the registered callback function. 


Definition: 
typedef void (*PFENMEDIANOTIFY) 
( 
void * pUser, 
AEEMediaCmdNotify * pCmdNotify 
) 

















Members: 


pUser User specified data pointer 


pCmdNotify Callback event-specific information 


Comments: 
None. 


See Also: 
AEEMediaCmdNotify 
Return to the List of data structures 
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Q12 Fixed Point Format 


Description: 


Q12 means the Q-factor for fixed point is 12, i.e., any floating point number is 
converted into an integer using the formula: 


int32 int x = (int)(float x * 2112) 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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Q14 Fixed Point Format 


Description: 


Q14 means the Q-factor for fixed point is 14, i.e., any floating point number is 
converted into integer using the formula: 


int32 int x = (int)(float x * 2114) 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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Q16 Fixed Point Format 


Description: 


Q16 means the Q-factor for fixed point is 16, i.e., any floating point number is 
converted into an integer using the formula: 


int32 int x = (int)(float x * 2/16) 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 


890 


Erevi Data Types 


Q3D File Format 


Description: 
This is QUALCOMM's file format for 3D models. 


Definition: 
The .9g3D file has the following format: 
uint16 magic num; 
uint8 version; 
uintô num seg; 
uint8 num color; 
uint8 num texture; 
uint16 num vert; 
uint16 num st coord; 
uint16 num poly; 
int32 vert array; 
int16 vert norm array; 
uintô texture coord array 
AEE3DModelPoly polygon array 
AEE3DModelSegment segment array 
uint8 color map 


Members: 


magic num: a magic number identifying the file format; it should have the character 
QB. 


version: version number for the file, currently 1. 

num seg: number of segments. 

num color: number of colors. 

num texture: number of texture images. 

num vert: number of vertices. 

num st coord: number of texture coordinates. 

num poly: number of polygons (triangles). 

vert array: array of vertex (size = 3 x num vert). 

vert norm array: array of vertex norms (size = 3 x num vert). 
texture coord array: array of texture coordinates (size = 2 xnum st coord). 
polygon array: array of polygons (size = num poly). 

segment array: array of segments (size = num seg). 


color map: color map (size = num color*4). Each entry in the color map is 4 bytes 
(RGBA). 
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Comments: 
The Q3D file format uses the .q3d extension. 


See Also: 
User's guide on 3D file converter 
Return to the List of data structures 
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PFNNOTIFY 


Description: 
PFNNOTIFY specifies a data type which is a function pointer to a function type 


void foo(void * pData).. 


Definition: 
typedef void (* PENNOTIFY) (void * pData); 


Members: 
None 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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PFNPOSITIONCB 


Description: 


PFNPOSITIONCB specifies the type of the callback function passed to 
ISHELL GetPosition(). 


Definition: 
typedef void (* PENPOSITIONCB) 
( 
void * pUser, 
AEEPositionInfo * pdlã, 
int nErr 


); 

















Members: 


pUser User data. 
pli Position location information. 
nErr Error code. 


Comments: 
None. 


See Also: 
AEEPositioninfo 
ISHELL GetPosition() 
Return to the List of data structures 
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PFNRINGEREVENT 


Description: 


PFNRINGEREVENT specifies the type of notification function registered using 
IRINGERMGR RegisterNotify(). 


Definition: 
typedef void (* PENRINGEREVENT) 
( 
void * pUser, 
AEERingerEvent evt, 
uint32 dwParm, 
int nErr 


); 



































Members: 
pUser User data. 
evt The event that specifies the reason for the notification. 
dwParm Contains event-specific information. 
nErr Error codes: 


AEE SUCCESS, if successful. 
Error code, if otherwise 


Here are the different notifications sent and their event specific parameters: 

ARE PLAY: Sent when play is done or when IRINGERMGR stop is called. 
dwparam = O. 
nErr is EENCOMPLETEITEM if play was still going on, 
nErr is O if play is done 

ARE CREATE: Sent when creation of the ringer is done or error. 
dwParam contains id of Ringer. 
nErr: AEE SUCCESS or EFAILED 

ARE WRITE: Sent any time a write occurs to the Ringer File. 
dwParam: number of bytes written to file. 
nErr is setto AEE SUCCESS 


Comments: 
None 


See Also: 
AEERingerEvent 
IRINGERMGR RegisterNotify() 
Return to the List of data structures 
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PFNSIONOTIFY 


Description: 
This function is called by the OEM layer to notify BREW of certain state transitions. 
Typically, this function must be called to notifiy BREW of any changes to the state flags 
described below. However, transitions of OEMBTSIO ST READABLE and 
OEMBTSIO ST WRITEABLE flags from TRUE to FALSE shall *not* result in a call to 
this function. 


When OEMBTSIO Init() is called, BREW will assume the current state is O (zero), so 
if any state flags are TRUE, PFNSIONOTIFY should be called at that point. 


Prototype: 
void (*PFNBTSIONOTIFY) (uint32 nPort, uint32 unState); 
Parameters: 
nPort The ID of the BT port (0, when only one BT port is supported). 
unState One of the following events: 
OEMBTSIO ST READABLE: this flag is TRUE when the receive 
queue is ready for reading. The precise meaning of “ready” is defined 
in the description of the OEMSIO SetTriggers() function. 
OEMBTSIO ST WRITEABLE: this flag is TRUE when the transmit 
queue is ready for writing. The precise meaning of "ready" is defined 
in the description of the OEMSIO SetTriggers() function. 
OEMBTSIO ST DISCONNECTED: this flag is TRUE when the Portis 
Closed 
OEMBTSIO ST CONNECTED: This flags is set when the Portis 
connected to a remote device 
OEMBTSIO ST CONNECTFAILED: This flag is set when device fails 
to connect to remote unit. 
Comments: 
None 
See Also: 
None 


Return to the List of data structures 
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PhonesState 


Description: 


PhoneState is used in ITAPI| GetStatus() to get the current state of the device. This is 
one of the members in the TAPIStatus data structure that is filled by the 
ITAPI GetStatus() function. 


Definition: 
typedef enum 

f 
PS OFFLINE, 
PS IDLE, 
PS. INCOMING, 
PS ORIG, 
PS. CONVERSATION 
; PhonesState; 














Members: 
PS OFFLINE Device is in offline state. 
PS IDLE Device is in Idle state. 
PS INCOMING There is an incoming call to the device. 
PS ORIG Device is in the process of originating a call. 


PS CONVERSATION Device is in the middle of a call. 


Comments: 
None 


See Also: 
TAPIStatus 
Return to the List of data structures 
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RGBVAL 


Description: 


The RGB value for a color is defined using this data type. The eight-bit values for red, 
green, blue are stored in 32-bits as follows: 





The reserved bits are filled with zeros. 


Definition: 
typedef uint32 RGBVAL 


Members: 
None 


Comments: 


The user can create their own colors using the MAKE RGB macro with their values for 
red, green, and blue to get the corresponding RGBVAL. 


See Also: 
None 
Return to the List of data structures 
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SocklOBlock 


Description: 


A single structure describes an individual block of memory from which data is read or 
to which data is written. 


Arrays of SockIOBlock structures are used in calls to ISOCKET ReadV() and 
ISOCKET WriteV() to describe data that is sent/received as a continuous stream even 
when, in memory, it is scattered among several blocks. 


Definition: 
typedef structure 
í 
byte * pbBuffer; 
uint16 wLen; 
) SockTOBlock; 


Members: 


pbBuffer Data buffer. 
wLen Length of buffer. 


Comments: 
None 


See Also: 
None 
Return to the List of data structures 
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Sprite Properties 


Description: 


Data Types 


These properties apply to each sprite in the AEESpriteCmd structure. 


Definition: 


SPRITE SIZE 8x8 
SPRITE SIZE 16X16 
SPRITE SIZE 32X32 
SPRITE SIZE 64x64 
SPRITE SIZE MAX 
SPRITE SIZE END 


SPRITE FLIP X 

SPRITE FLIP Y 

SPRITE ROTATE 90 
SPRITE ROTATE 180 
SPRITE ROTATE, 270 
SPRITE SCALE 2 
SPRITE SCALE 4 
SPRITE SCALE 8 
SPRITE SCALE EIGHTH 
SPRITE SCALE QUARTER 
SPRITE SCALE HALF 


Sprite sizes, for unSpriteSize field. 


Special value for unSpriteSize signaling end of 
command array. 


Simple transformation flags for unTransform field. 
These may be combined. To combine a flip with a 
rotate, xor the two values. (This is to accommodate 
SPRITE FLIP Ywhichis SPRITE FLIP X| 
SPRITE ROTATE 180.) 


SPRITE MATRIX TRANSFOR This flags goes in unTransform, and specifies that a 


M 


SPRITE LAYER 0 
SPRITE LAYER 1 
SPRITE LAYER 2 
SPRITE LAYER 3 
SPRITE LAYER HIDDEN 


Members: 
None 


complex transform should be performed using the 
unMatrixTransform field. When this flag is set, all 
other flags in unTransform are ignored. 


Valid layers for unLayer field. 
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Comments: 
Note: All transformation use the sprite's center as the origin. 


See Also: 
AEESpriteCmd 
Return to the List of data structures 
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TAPIStatus 


Description: 


Data Types 


TAPIStatus is used in ITAP|I GetStatus() to get the current TAPI status on the device. 
This is also sent as dwParam member of the EVT NOTIFY event when applications 
have registered for TAPI Status notifications. 


Definition: 
typedef structure 
f 


char szMobil 





|eID [MOBILE ID LEN +1]; 











PhoneState state; 


flg bData:l; 
Digital: 
Roaming:1; 


flg 
flg 








£flg bE911Cal 


1; 


lbackMode: 1; 





flg 
flg 





b 
b 
flg bCallEnded:1; 
b 
b 
b 


Restricted:1; 
Registered:1; 


flg bDormancy:l; 
) TAPIStatus; 


Members: 


szMobilelD 
state 

bdata 
bDigital 
bRoaming 
bCallEnded 


bE911CallbackMode 
bRestricted 
bRegistered 


bDormancy 


Comments: 
None 


See Also: 
PhoneState 
ITAPI GetStatus() 


Mobile ID (digits). 

Current device state. This is an enum of type PhoneState. 
Indicates if the device is in a data call. 

Indicates if the device is in digital service. 

Indicates if the device is in a roaming state. 

Indicates if this notification was sent as part of a call-end. This 
flag is useful when applications have registered to be notified 
with updated TAPIStatus information for any changes. 
Registrations for notifications are done through the 

ISHELL RegisterNotify() function. 


Indicates if the device is in the E911 callback mode. 
This member is not used. 


System registration accomplished, set to TRUE if not 
applicable. 


Network fully supports dormancy, FALSE is not applicable. 
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Return to the List of data structures 
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Tile Map Properties 


Description: 
These properties apply to each tile map, in the AEETileMap structure. 


Definition: 

TILE SIZE 8X8 

TILE SIZE 16X16 

TILE SIZE 32X32 

TILE SIZE 64X64 Values for unTileSize field. 

MAP FLAG WRA Flag for unFlags field. (Currently the only flag.) If 

P MAP FLAG WRAP is set, map should wrap around. For 
instance, ifa map is 16 tiles wide, column O would be displayed 
after column 15. 

MAP SIZE 1 

MAP SIZE 2 

MAP SIZE 4 

MAP SIZE 8 

MAP SIZE 16 

MAP SIZE 32 

MAP SIZE 64 

MAP SIZE 128 

MAP SIZE 256 

MAP SIZE 512 

MAP SIZE 1024 Values for w and h fields. 


Comments: 
None 


See Also: 
AEETileMap 
Return to the List of data structures 
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Tile Properties 


Description: 
These flags apply to each tile, in the elements of the pMapArray array field of 
AEETileMap. 
Definition: 
TILE FLIP X Flip tile over X axis. 
TILE FLIP Y Flip tile over Y axis. (Note:this is a composite of FLIP X and 
ROTATE 180.) 
TILE ROTATE 90 Rotate tile 90 degrees counter clockwise. 


TILE ROTATE 180 Rotate tile 180 degrees counter clockwise. 
TILE ROTATE 270 Rotate tile 270 degrees counter clockwise. 
TILE TRANSPARENT Tile should be drawn transparently. 

TILE INDEX MASK Mask of bits used for tile index. 


TILE INDEX NOTHING This special index value means don't draw anything for this tile. 
This is funtionally equivalent to blitting a tile that is completely 
transparent, but this is faster. 


Members: 
None 


Comments: 
None 


See Also: 
AEETileMap 
Return to the List of data structures 
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AECHAR 

AEE Events 

AEE ITextCtl Properties 
AEE Static Properties 

AEE Active() 

AEE ADDR RECID NULL 
AEE Autolnstall() 

AEE BuildPath() 

AEE CheckPtr() 

AEE CheckStack() 

AEE CreateControl() 

AEE DBError 

AEE DBRecinfo 

AEE Dispatch() 

AEE EnumkRegHandlers() 
AEE Event() 

AEE Exception() 

AEE Exit() 

AEE FreeMemory() 

AEE GetAppContext() 
AEE GetClassinfo() 

AEE GetShell() 

AEE. Init() 

AEE Islnitialized() 

AEE IsTestDevice() 

AEE Key() 

AEE KeyHeld() 

AEE KeyPress() 

AEE KeyRelease() 

AEE LinkSysObject() 

AEE NetEventOccurred() 
AEE RegisterForDataService() 
AEE RegisterForValidTime() 
AEE Resume() 

AEE ResumeEx() 

AEE SetAppContext() 
AEE SetEventHandler() 
AEE SetSysTimer() 

AEE SocketEventOccurred() 
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733 
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438 
739 


440 
441 
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767 


444 
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448 
449 


451 
452 


454 
455 


457 
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460 
461 


463 
464 


466 
467 
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AEE Suspend() 

AEE TimerExpired() 
AEE UnlinkSysObject() 
AEE3DColor 
AEE3DCoordinateTransformType 
AEES3DCullingType 
AEE3DEventNotify 
AEE3DLight 
AEE3DLightingMode 
AEE3DLightType 
AEE3DMaterial 
AEE3SDMatrixMode 
AEE3DModelData 
AEE3DModelPoly 
AEE3DModelSegment 
AEE3DPoint 
AEE3DPoint16 
AEE3DPrimitiveType 
AEE3DRenderType 
AEESDRotateType 
AEESDTexture 
AEESDTextureSamplingType 
AEE3DTextureType 
AEESDTextureWrapType 
AEE3DTLVertex 
AEE3DTransformMatrix 
AEE3DVertex 
AEEAppStart 
AEEBitFont NewFromBBF() 
AEEBitmapInfo 
AEECallback 
AEECallHistoryEntry 
AEECallHistoryField 
AEECameraNotify 
AEEDevicelnfo 
AEEDeviceltem 
AEEDNSClass 
AEEDNSItem 
AEEDNSResponse 
AEEDNSType 
AEEFilelnfoEx 
AEEFileUselnfo 
AEEFontinfo 
AEEGPSConfig 
AEEGPSInfo 
AEEGSM1xControl statusType 
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AEEGSM1xSig NotifyMessageType 
AEEGSM1xSig RejectMessageType 
AEEGSM1xSig SignalingMessageType 
AEELogBinMsgType 
AEELogBucketType 
AEELogltemType 
AEELogParamType 
AEELogRcdHdrType 
AEELogVerHdrType 
AEEMedia 

AEEMedia AddRef() 
AEEMedia CallbackNotify() 
AEEMedia Delete() 
AEEMedia GetMediaParm() 
AEEMedia GetState() 
AEEMedia GetTotalTime() 
AEEMedia Init() 

AEEMedia New() 
AEEMedia Pause() 
AEEMedia Play() 
AEEMedia Querylnterface() 
AEEMedia Record() 
AEEMedia RegisterNotify() 
AEEMedia Release() 
AEEMedia Resume 
AEEMedia Seek() 
AEEMedia SetMediaParm() 
AEEMedia Stop() 
AEEMediaCallback 
AEEMediaCmdNotify 
AEEMediaData 
AEEMediaMIDISpec 
AEEMediaMP3Spec 
AEEMediaSeek 

AEENotify 

AEENotifyStatus 
AEEObjectHandle 
AEEObjectMgr GetObject() 
AEEObjectMgr Register() 
AEEObjectMgr Unregister() 
AEE Orientationinfo 
AEEParminfo 
AEEPosAccuracy 
AEEPositioninfo 
AEERasterOp 

AEERect 
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AEERingerCat 
AEERingerCatID 
AEERingerEvent 
AEERingerlD 
AEERingerlnfo 
AEERLP3Cfg 

AEE Sectorinfo 

AEESize 

AEESMSMsg 
AEESMSTextMsg 
AEESoundPlayerFile 

AEE TextinputMode 

AEE TextinputModelnfo 
AEETileMap 

AEE TransformMatrix 
AEEUDPUrgent 

Camera Command codes 
Camera Control Parameters 
Camera Status codes 
CameraExifTaglinfo 
CMediaFormat 

CMediaMIDI 
CMediaMIDIOutMsg 
CMediaMIDIOUtQCP 
CMediaMP3 

CMediaPMD 

CMediaQCP 

Configuation Parameters 
CtiAddltem 

CtlValChange 

FileAttrib 

FileInfo 
GSMSMSEncodingType 
GSMSMSMsg 
GSMSMSMsgType 
GSMSMSRawMsg 
GSMSMSStatusType 
GSMSMSStorageType 

I3D AddRef() 

I3D ApplyModelViewTransform() 
I3D CalcVertexArrayColor() 
I3D CalcVertexArrayNormal() 
I3D ClearFrameBuf() 

I3D Events 

I3D GetClipRect() 

I3D GetCoordTransformMode() 
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I3D GetCullingMode() 

I3D GetDestination() 

I3D GetFocalLength() 

I3D GetLight() 

I3D GetLightingMode() 

I3D GetMaterial() 

I3D GetModelViewTransform() 
I3D GetRenderMode() 

I3D GetScreenMapping() 

I3D GetTexture() 

I3D GetViewDepth() 

I3D PopMatrix() 

I3D PushMatrix() 

I3D Querylnterface() 

I3D RegisterEventNotify() 
I3D Release() 

I3D RenderTriangleFan() 

I3D RenderTriangles() 

I3D RenderTriangleStrip() 
I3D ResetZBuf() 

I3D SetClipRect() 

I3D SetCoordTransformMode() 
I3D SetCullingMode() 

I3D SetDestination() 

I3D SetFocalLength() 

I3D SetLight() 

I3D SetLightingMode() 

I3D SetMaterial() 

I3D SetModelViewTransform() 
I3D SetRenderMode() 

I3D SetScreenMapping() 

I3D SetTexture() 

I3D SetViewDepth() 

I3D StartFrame() 

I3DModel AddRef() 
I3DModel Draw() 

|3DModel GetModelData() 
I3DModel GetModelVertexList() 
I3DModel Load() 

I3DModel Querylnterface() 
I3DModel Release() 
I3DModel SetSegmentMVT () 
I3DModel SetTextureTbI() 
I3DUtil AddRef() 

I3DUtil cos() 

I3DUtil GetRotateMatrix() 
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I3DUtil GetRotateVMatrix() 
I3DUtil GetUnitVector() 

I3DUtil GetViewTransformMatrix() 
I3DUtil MatrixMultiply() 

I3DUtil QueryInterface() 

I3DUtil Release() 

I3DUtil SetldentityMatrix() 
I3DUtil SetTranslationMatrix() 
I3DUtil sin() 

I3DUtil sart() 

IBITMAP AddRef() 

IBITMAP BltIn() 

IBITMAP BItOut() 

IBITMAP CreateCompatibleBitmap() 
IBITMAP DrawHScanline() 
IBITMAP DrawPixel() 

IBITMAP FillRect() 

IBITMAP Getlnfo() 

IBITMAP GetPixel() 

IBITMAP GetTransparencyColor() 
IBITMAP NativeToRGB() 
IBITMAP Querylnterface() 
IBITMAP Release() 

IBITMAP RGBToNative() 
IBITMAP SetPixels() 

IBITMAP SetTransparencyColor() 
IBITMAPCTL AddRef() 
IBITMAPCTL Enable() 
IBITMAPCTL NotifyRelease() 
IBITMAPCTL Querylnterface() 
IBITMAPCTL Release() 
IBITMAPCTL Restrict() 
ICALLHISTORY AddEntry() 
ICALLHISTORY Clear() 
ICALLHISTORY. Enumtinit() 
ICALLHISTORY. EnumNext() 
ICALLHISTORY UpdateEntry() 
ICAMERA AddOverlay() 
ICAMERA AddRef() 

ICAMERA ClearOverlay() 
ICAMERA DeferEncode() 
ICAMERA EncodeSnapshot() 
ICAMERA GetDisplaySizeList() 
ICAMERA GetFrame() 
ICAMERA GetMode() 
ICAMERA GetParm() 
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ICAMERA GetSizeList() 
ICAMERA IsBrightness() 
ICAMERA IsContrast() 
ICAMERA IsMovie() 
ICAMERA IsSharpness() 
ICAMERA IsSupport() 
ICAMERA IsZoom() 
ICAMERA Pause() 

ICAMERA Preview() 
ICAMERA Querylnterface() 
ICAMERA RecordMovie() 
ICAMERA RecordSnapshot() 
ICAMERA RegisterNotify() 
ICAMERA Release() 
ICAMERA Resume() 
ICAMERA RotateEncode() 
ICAMERA RotatePreview() 
ICAMERA SetAudioEncode() 
ICAMERA SetBrightness() 
ICAMERA SetContrast() 
ICAMERA SetDisplaySize() 
ICAMERA SetFramesPerSecond() 
ICAMERA SetMediaData() 
ICAMERA SetParm() 
ICAMERA SetQuality() 
ICAMERA SetSharpness() 
ICAMERA SetSize() 
ICAMERA SetVideoEncode() 
ICAMERA SetZoom() 
ICAMERA Start() 

ICAMERA Stop() 

IDC COMMAND RESERVED 
IDIB 

IDIB AddRef() 

IDIB FlushPalette() 

IDIB Querylnterface() 

IDIB Release() 

IDIB TO IBITMAP() 

IDNS AddQuestion() 

IDNS AddRef() 

IDNS GetResponse() 

IDNS ParseDomain() 

IDNS Querylnterface() 

IDNS Release() 

IDNS Start() 

IDOWNLOAD Acquire() 
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IDOWNLOAD AutoDisable() 
IDOWNLOAD Cancel() 

IDOWNLOAD CheckltemUpgrade() 
IDOWNLOAD CheckUpgrades() 
IDOWNLOAD Continue() 
IDOWNLOAD Credit() 
IDOWNLOAD Delete() 
IDOWNLOAD Enum() 
IDOWNLOAD EnumRaw() 
IDOWNLOAD Get() 

IDOWNLOAD GetADSCapabilities() 
IDOWNLOAD GetADSList() 
IDOWNLOAD GetAIlApps() 
IDOWNLOAD GetApplIDList() 
IDOWNLOAD GetAppIDListEx() 
IDOWNLOAD GetAutoDisableList() 
IDOWNLOAD GetAvailable() 
IDOWNLOAD GetCategory() 
IDOWNLOAD GetCategoryList() 
IDOWNLOAD GetConfigltem() 
IDOWNLOAD GetEULA() 
IDOWNLOAD GetHeaders() 
IDOWNLOAD Getlteminfo() 
IDOWNLOAD GetltemList() 
IDOWNLOAD GetModinfo() 
IDOWNLOAD GetSize() 
IDOWNLOAD GetSizeEx() 
IDOWNLOAD Lock() 

IDOWNLOAD LogEnuminit() 
IDOWNLOAD LogEnumNext() 
IDOWNLOAD OnsStatus() 
IDOWNLOAD Restore() 
IDOWNLOAD Search() 
IDOWNLOAD SetADS() 
IDOWNLOAD SetHeaders() 
IDOWNLOAD SetSubscriberlD() 
IFONT AddRef() 

IFONT DrawText() 

IFONT Getlnfo() 

IFONT MeasureText() 

IFONT QuerylInterface() 

IFONT Release() 

IGSM1xControl ActivateNonGSM1xMode() 
IGSM1xControl EnableGSM1xMode() 
IGSM1xControl GetAvailableModes() 
IGSM1xControl GetCurrentMode() 
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IGSM1xControl GetDFPresence() 
IGSM1xControl Get6GSM1xPRL() 
IGSM1xControl Get6SM1xSIDNIDPairs() 
IGSM1xControl GetPLMN() 


IGSM1xControl GetSupportedProvisioningModes() 286 


IGSM1xControl GetUIMUniqueld() 
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284 


287 


IGSM1xControl ProvisionGSM1xParameters() 288 


IGSM1xControl Set6GSM1xPRL() 
IGSM1xControl Set6GSM1xSIDNIDPairs() 
IGSM1xControl SetPLMN() 
IGSM1xControl ValidatePRL() 
IGSM1xSig GetStatus() 

IGSM1xSig SendSignalingMessage() 
IGSM1xSig SendSignalingReject() 
IGSMSMS CreateDefaultMessage() 
IGSMSMS DecodeMessage() 
IGSMSMS DecodeUserData() 
IGSMSMS DeleteAllMessages() 
IGSMSMS DeleteMessage() 

IGSMSMS EncodeUserData() 
IGSMSMS GetMemoryCapExceededFlag() 
IGSMSMS GetMessage() 

IGSMSMS GetMessageStatus() 
IGSMSMS GetSCAddress() 

IGSMSMS GetStatusReport() 

IGSMSMS GetStoreSize() 

IGSMSMS GetTPMR() 

IGSMSMS Isilnit() 

IGSMSMS MoveMessage() 

IGSMSMS SendMoreMemoryAvailable() 
IGSMSMS SendSMSDeliverReport() 
IGSMSMS SendSMSSubmit() 
IGSMSMS SetMemoryCapExceededFlag() 
IGSMSMS SetMessageStatus() 
IGSMSMS SetSCAddress() 

IGSMSMS SetTPMR() 

IGSMSMS StoreMessage() 

IGSMSMS StoreStatusReport() 
ILOGGER AddRef() 

ILOGGER GetParam() 

ILOGGER Printf() 

ILOGGER Putltem() 

ILOGGER PutMsg() 

ILOGGER Release() 

ILOGGER SetParam() 

INAddr 
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INPort 

IOEMDISP Backlight() 
IOEMDISP GetDefaultColor() 
IOEMDISP GetDeviceBitmap() 
IOEMDISP GetPaletteEntry() 
IOEMDISP GetSymbol() 
IOEMDISP GetSystemFont() 
IOEMDISP MapPalette() 
IOEMDISP SetAnnunciators() 
IOEMDISP SetPaletteEntry() 
IOEMDISP Update() 

IPOSDET AddRef() 

IPOSDET GetGPSConfig() 
IPOSDET GetGPSInfo() 
IPOSDET GetOrientation() 
IPOSDET GetSectorlnfo() 
IPOSDET Querylnterface() 
IPOSDET Release() 

IPOSDET SetGPSConfig() 
IRINGERMGR AddRef() 
IRINGERMGR Create() 
IRINGERMGR EnumCategoryInit() 
IRINGERMGR EnumNextCategory() 
IRINGERMGR EnumNextRinger() 
IRINGERMGR EnumRingerlnit() 
IRINGERMGR GetFormats() 
IRINGERMGR GetNumberFormats() 
IRINGERMGR GetRingerlD() 
IRINGERMGR GetRingerlnfo() 
IRINGERMGR Play() 
IRINGERMGR PlayEx() 
IRINGERMGR PlayFile() 
IRINGERMGR PlayStream() 
IRINGERMGR RegisterNotify() 
IRINGERMGR Release() 
IRINGERMGR Remove() 
IRINGERMGR SetRinger() 
IRINGERMGR Stop() 

IRUIM AddRef() 

IRUIM CHVDisable() 

IRUIM CHVEnable() 

IRUIM GetCHVStatus() 

IRUIM Getld() 

IRUIM GetPrefLang() 

IRUIM IsCardConnected 

IRUIM PINChange() 
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IRUIM PINCheck() 

IRUIM Querylnterface() 

IRUIM Release() 

IRUIM UnblockCHV() 

IRUIM VirtualPINCheck() 
ITAPI AddRef() 

ITAPI ExtractSMSText() 
ITAPI GetCallerlD() 

ITAPI GetStatus() 

ITAPI IsDataSupported() 
ITAPI IsVoiceCall() 

ITAPI MakeVoiceCall() 
ITAPI OnCallEnd() 

ITAPI OnCallStatus() 

ITAPI Release() 

ITAPI SendSMS() 

ITEXTCTL AddRef() 
ITEXTCTL EnumModelnit() 
ITEXTCTL EnumNextMode() 
ITEXTCTL GetCursorPos() 
ITEXTCTL GetinputMode() 
ITEXTCTL GetProperties() 
ITEXTCTL GetRect() 
ITEXTCTL GetText() 
ITEXTCTL GetTextPtr() 
ITEXTCTL HandleEvent() 
ITEXTCTL IsActive() 
ITEXTCTL Redraw() 
ITEXTCTL Release() 
ITEXTCTL Reset() 
ITEXTCTL SetActive() 
ITEXTCTL SetCursorPos() 
ITEXTCTL SetinputMode() 
ITEXTCTL SetMaxSize() 
ITEXTCTL SetProperties() 
ITEXTCTL SetRect() 
ITEXTCTL SetSoftkeyMenu() 
ITEXTCTL SetText() 
ITEXTCTL SetTitle() 
ITransform Properties 
ITRANSFORM AddRef() 
ITRANSFORM Querylnterface() 
ITRANSFORM Release() 
ITRANSFORM TransformBltComplex() 
ITRANSFORM TransformBltSimple() 
NativeColor 
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NetSocket 

NetState 

OEM AuthorizeDownload() 
OEM CheckMemaAvail() 
OEM CheckPrivacy() 
OEM DBClose() 

OEM DBCreate() 

OEM DBDelete() 

OEM DBFree() 

OEM DBInit() 

OEM DBMakeReadOnly() 
OEM DBOpen() 

OEM DBRecordAdda() 
OEM DBRecordCount() 
OEM DBRecordDelete() 
OEM DBRecordGet() 

OEM DBRecordNext() 
OEM DBRecordUpdate() 
OEM extract SMS text() 
OEM FloatToWStr() 
OEM format SMS msg() 
OEM format SMS text() 
OEM Free() 

OEM GetAddrBookPath() 
OEM GetAppPath() 
OEM GetCHType() 

OEM GetConfig() 

OEM GetDevicelnfo() 
OEM GetDevicelnfoEx() 
OEM GetltemStyle() 

OEM GetLogoPath() 
OEM GetMIFPath() 

OEM GetPath() 

OEM GetRAMFree() 
OEM GetRingerPath() 
OEM GetSharedPath() 
OEM InitHeap() 

OEM LockMem() 

OEM Malloc() 

OEM Notify() 

OEM Realloc() 

OEM SetConfig() 

OEM SimpleBeep() 

OEM TextAddChar() 

OEM TextCreate() 

OEM TextDelete() 
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OEM TextDraw() 

OEM TextEnumMode() 
OEM TextEnumModesinit() 
OEM TextGet() 

OEM TextGetCurrentMode() 
OEM TextGetCursorPos() 
OEM TextGetMaxChars() 
OEM TextGetModeString() 
OEM TextGetProperties() 
OEM TextGetRect() 

OEM TextGetSel() 

OEM TextKeyPress() 

OEM TextQueryModes() 
OEM TextQuerySymbols() 
OEM TextSet() 

OEM TextSetCursorPos() 
OEM TextSetEdit() 

OEM TextSetMaxChars() 
OEM TextSetProperties() 
OEM TextSetReci() 

OEM TextSetSel() 

OEM TextUpdate() 

OEM uasms config listeners() 
OEM UnlockMem() 

OEM UTF8ToWStr() 

OEM vxprintf() 

OEM WStrLower() 

OEM WStrToFloat() 

OEM WStrToUTF8() 

OEM WStrUpper() 
OEMAddr EnumNextRec() 
OEMAddr EnumRecinit() 
OEMAddr GetCatCount() 
OEMAddr GetCatList() 
OEMAddr GetFieldinfo() 
OEMAddr GetFieldinfoCount() 
OEMAddr GetNumRecs() 
OEMAddr RecordAdd() 
OEMAddr RecordDelete() 
OEMAddr RecordGetBylID() 
OEMAddr RecordUpdate() 
OEMAddr RemoveAllRecs() 
OEMAddrBook CommonExit() 
OEMAddrBook Commontlnit() 
OEMAddrBook Exit() 
OEMAddrBook Init() 
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OEMAppEvent 

OEMBTSDP CancelDiscovery() 
OEMBTSDP CloseLib() 
OEMBTSDP DiscoverDevices() 
OEMBTSDP GetDeviceName() 
OEMBTSDP GetServerChannel() 
OEMBTSDP Init() 

OEMBTSDP OpenLib() 
OEMBTSDP Shutdown() 
OEMBTSIO Close() 
OEMBTSIO DataAvailable() 
OEMBTSIO Init() 

OEMBTSIO Open() 
OEMBTSIO ProcessEvents() 
OEMBTSIO Read() 
OEMBTSIO Write() 
OEMCRC 16 step() 
OEMDebug Printf() 

OEMDebug VPrintf() 

OEMDisp New() 

OEMFS Close() 

OEMFS EnumNext() 

OEMFS EnumsStart() 

OEMFS EnumsStop() 

OEMFS GetDirlnfo() 

OEMFS GetFileAttributes() 
OEMFS GetLastError() 
OEMFS GetOpenFileAttributes() 
OEMFS Mkdir() 

OEMFS Open() 

OEMFS Read() 

OEMFS Remove() 

OEMFS Rename() 

OEMFS Rmdir() 

OEMFS Seek() 

OEMFS SpaceAvail() 

OEMFS SpaceUsed() 

OEMFS Tell() 

OEMFS Test() 

OEMFS Truncate() 

OEMFS Write() 

OEMLogger Printf() 
OEMLogger Putltem() 
OEMLogger PutMsg() 
OEMLoggerDMSS GetParam() 
OEMLoggerDMSS PutRecord() 
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OEMLoggerDMSS SetParam() 
OEMLoggerFile GetParam() 
OEMLoggerFile PutRecord() 
OEMLoggerFile SetParam() 
OEMLoggerWin GetParam() 
OEMLoggerWin PutRecord() 
OEMLoggerWin SetParam() 
oemLogType 

OEMMDS Final() 

OEMMDS Init() 

OEMMDS5 Update() 
OEMMedia DetectType() 
OEMNet CloseNetlib() 
OEMNet GetPPPAuth() 
OEMNet GetRLP3Cfg() 
OEMNet GetUrgent() 
OEMNet MylIPAddr() 
OEMNet NamesServers() 
OEMNet OpenNetlib() 
OEMNet PPPClose() 
OEMNet PPPOpen() 
OEMNet PPPSleep() 
OEMNet PPPState() 
OEMNet SetPPPAuth() 
OEMNet SetRLP3Cfg() 
OEMOS ActiveTaskID() 
OEMOS BrewHighPriority() 
OEMOS BrewNormalPriority() 
OEMOS CancelDispatch() 
OEMOS GetLocalTime() 
OEMOS GetTimeMS() 
OEMOS GetUptime() 
OEMOS LocalTimeOffset() 
OEMOS SetTimer() 

OEMOS SignalDispatch() 
OEMOS Sleep() 

OEMRan GetNonPseudoRandomBytes() 
OEMRan Next() 

OEMRan Seed() 
OEMRegistry DetectType() 
OEMRUIMAddr GetFuncs() 
OEMSocket Accept() 
OEMSocket AsyncSelect() 
OEMSocket Bind() 
OEMSocket Close() 
OEMSocket Connect() 


920 


601 
602 


604 
605 


607 
884 


610 
611 


613 
614 


616 
617 


619 
620 


622 
623 


625 
630 


632 
633 


635 
636 


638 
639 


642 
643 


627 
384 


652 
653 


655 


brew. 


Functions and Data Types 


OEMSocket GetNextEvent() 
OEMSocket GetPeerName() 
OEMSocket GetSockName() 
OEMSocket Listen() 
OEMSocket Open() 
OEMSocket Read() 
OEMSocket Readv() 
OEMSocket RecvFrom() 
OEMSocket SendTo() 
OEMSocket Shutdown() 
OEMSocket Write() 
OEMSocket Writev() 
OEMSound DeletelInstance() 
OEMSound GetLevels() 
OEMSound GetVolume() 
OEMSound Init() 
OEMSound Newlnstance() 
OEMSound PlayFregTone() 
OEMSound PlayTone() 
OEMSound PlayToneList() 
OEMSound SetDevice() 
OEMSound SetVolume() 
OEMSound StopTone() 
OEMSound StopVibrate() 
OEMSound Vibrate() 
OEMSoundPlayer FastForward() 
OEMSoundPlayer GetTotalTime() 
OEMSoundPlayer Pause() 
OEMSoundPlayer Play() 
OEMSoundPlayer PlayRinger() 
OEMSoundPlayer Resume() 
OEMSoundPlayer Rewind() 
OEMSoundPlayer Stop() 
OEMSoundPlayer Tempo() 
OEMSoundPlayer Tune() 
PFNCBCANCEL 
PFNDLTEXT 
PFNMEDIANOTIFY 
PFNNOTIFY 
PFNPOSITIONCB 
PFNRINGEREVENT 
PFNSIONOTIFY 

PhoneState 

Q12 Fixed Point Format 

Q14 Fixed Point Format 

Q16 Fixed Point Format 
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Q3D File Format 
RGBVAL 
SockIOBlock 
Sprite Properties 
TAPIStatus 

Tile Map Properties 
Tile Properties 
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